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Introduction || 


How this Manual is Organized 


vt The first part of this manual, “Color System Overview,’ is divided into six chap- 
ters. Chapter 1—“Basic Concepts” introduces the concepts necessary to under- 
stand and use the color system. This chapter is further divided into sections that 
describe concepts and functions of the color system, such as color maps, ALUs, 
and color objects. 


The remaining five chapters in the first part describe in much greater detail each 
of the terms, concepts, and functions described in Chapter 1. Included in each 
of these chapters are the software messages and functions relevant to the fea- 
tures described. 


The next part of the manual is the ‘Tutorial.’ This part introduces you to the 
steps required for creating a program that uses the graphical capabilities of the 
color system, including creating screens and windows, creating and manipulat- 
ing ALUs, drawing objects on selected windows, and using hardware and soft- 
ware overlays. 


The specific functions performed by each of the various controllers are || 
described in the next part, “Color System Hardware Features.” A separate chap- Hii 
ter lists the features of each of the six hardware options. ili 


‘Auxiliary Systems”’ describes two software systems that are not loaded with the 
color system software but that you might find useful. Chapter 10—“‘Color Edi- | 
Th tor” describes how to use the Symbolics color editor to blend colors using one {|| 
oo of several models. Chapter 11—“IMAN System” describes the Symbolics Image | 
Management System, which is useful in saving and displaying images. HII 


The appendixes contain information on a variety of tangential topics such as 
possible problems you might encounter, graphics mixin methods for drawing 
polygons with different characteristics, a guide to the color demonstration pro- 


— gram, how to use icons in menus, information about using bitmaps in the color 
system, and a glossary of terms. 
a Last, the index contains an alphabetical reference of topics of interest to the 


ee color system user. Of particular interest is the inclusion of page references for all 
software messages and functions. 
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How to Use this Manual 


This manual is intended for use both as an instructional and reference manual. 
As a result, you might skip over some sections if they do not pertain to the appli- 
cation you are working on, but you might need to read other sections from start 
to finish. If you are new to color graphics or to the Symbolics color system, you 
should read Chapter 1—“‘Basic Concepts.” Then go on to read chapters 2 
through 5 for an understanding of how you use the color system software to 
create and manipulate images on the color screen. Chapter 6—‘‘Additional Color 
System Features” describes some of the features of the color system that you 
might or might not need to know about immediately; you can skip this chapter 
if you do not need to use the features described on the first page of Chapter 6. 


Once you have read chapters 1 through 5 (and optionally 6), go on to 
Chapter 7—‘‘Color System Tutorial.’ The tutorial takes you through the steps 
necessary for writing programs that make images on the color monitor. If you 
are familiar with graphics programming, read the tutorial for recommended 
procedures and examples of how to use the Symbolics color system. 


To find the specific features of the hardware configuration present in your color 
system, consult chapters 8 and 9 in “Color System Hardware Features.” 

Chapter 8 describes the hardware features, while Chapter 9 is divided into sec- 
tions that list the features available for each of the color systems. 


The remainder of the manual is useful as reference material and need not be 
read straight through. Consult the “Overview” if you are not sure what you are 
looking for and need to find it by context; if you do know what you are looking 
for and want to find it quickly, consult the index. 
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Basic Concepts 


The Symbolics color system is a Lisp Machine with the addition of one or more 
color boards, some cabling between your machine and your office, and a color 
monitor. 


The following terms are used throughout the manual. You should understand 
them before continuing. 


Color screen The color software presents the color hardware as a screen, 
which has a superset of the capabilities of the familiar 
black-and-white screen. 


Screen array All screens have a screen array, which is a 2D array of pixels. 
On black-and-white screens, the pixels contain only 1 bit. 
On color screens, the size of pixels is usually 8 or 32 bits. 


Color window A window whose ultimate superior is a color screen. Use 
the same window flavors that are used on black-and-white 
windows. 

Color monitor The actual box containing the picture tube you are looking 


at. The term color monitor is used to emphasize what you 
see rather than the underlying software used to generate the 
picture. 


Color map A translation table used by the color screen to transform 
pixel values into the colors you see on the monitor. 


There is a red map, a green map, and a blue map; how 
pixels use the three color maps is determined by the map 
mode. 


Each color map is divided into segments, the number of 
which depends on the hardware configuration. Each 
segment is further divided into s/ots or index entries for 
each color component. For example, in a system with four 
color map segments, two bits in the controller (set by 
software) determine the segment to use; as modified by the 
map mode in use, the pixel data is the number of the slot or 
index entry to use within the selected segment. 
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Color ALU 


Color object 


You can change the color of an image on the screen by 
selecting a different color map segment. 


Map modes determine how pixel data is interpreted by the 
color map, and therefore how the color map is used. There 
are different map modes for 8-bit, 12-bit, and 24-bit pixels. 
Additional map modes control the selection of overlay 
colors. 


The two most common map modes are 8-bit and 24-bit. In 
8-bit mode, the 8 bits of the pixel data select the same slot 
number in the active segment of each color map (red, 
green, and blue). This means there are a total of 256 color 
slots available per map segment. 


In 24-bit mode, 8 bits worth of the pixel data is used to 
determine the slot in the red color map segment, a different 
8 bits determine the slot in the blue map segment, and the 
remaining 8 bits determine the slot in the green map 
segment. This means that there are a total of 16,777,216 
color slot combinations available per color map segment. 


A specification for an operation on a pixel. 


An abstract specification for a color. 


How You Get What You See 


The static picture you see on your color monitor is determined by three things: 


> The color screen and its associated state, especially its map mode 


> The contents of the screen array 


> The contents of the color map 


AS a consequence, putting a picture on a color screen requires you to control all 


three things. 


The state of the color screen and the contents of the color maps are usually 
standardized and are not frequently changed. Color screens are created with a 
color map in the most useful map mode available. 


The primary means of making pictures is to manipulate the screen array; this is 
normally done by drawing on color windows. You can draw on color windows 
using the same drawing operations as on black-and-white windows. These oper- 
ations (for example, :draw-triangle) effectively specify a set of pixels to be 
modified. A color ALU is a specification for how to modify the pixels. 
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For example, take a conceptually simple operation such as “draw a red circle.” 
To accomplish this, you must have your hands on the following objects: 


A color window (and implicitly, the color screen that is the ultimate supe- 
rior of that window). 


The color map associated with the color screen. 


A color ALU that produces the desired shade of red on your color moni- | 
tor when used to draw on the color window (and implicitly, that uses the 
screen’s color map and map mode). | 


Suggestions for Learning to Use the Color System | 


Before anything else, you need to create a color screen and a color window. 
After that, if you are new to the Symbolics color system, approach the problem 
of creating color graphics in a step-by-step manner. Create simple graphics at 
first, then gradually add more complex features of the system. As a beginner, it . 
is easiest to use the default color maps and map mode, so ignore the details of 
color screen and color map setup. Likewise, many details about color ALUs are 
confusing even to advanced users. Ignore the confusing details until you need to 
understand them and concentrate on understanding the effects of color maps 
and ALUs on your images. Even though it is not strictly correct, think of a color | 
ALU as specifying “a color,’ and use color ALUs to draw pictures on a color | 
window; however, keep in mind that you are using an approximate model. 


Additional Color System Features | 


In addition to the basic graphics functions already described, the color system 
supports additional features, such as key output, line index table, and pan and | 
zoom, that might be useful in specialized applications. Some of these features, | 
such as key output, require special hardware options. The software messages | 
that apply to these additional features are described in Chapter 0—‘‘Additional 
Color System Features.” | 
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Color Window System 


The color system software is based on the 3600-family window system and is 
compatible with the black-and-white screen. Most 3600-family window system 
methods added for color screens also work on the black-and-white screen if 
there is a meaningful analog. 


This chapter describes how to create and manipulate color screens and win- 
dows. It also lists and describes the software messages and functions necessary 
to create and manipulate screens and windows. 


Getting Started 


‘eH If the color system is not part of a site’s world, you need to load the color sys- 
tem software with the following command processor command: 


Load System Color 


This loads the color system. Now you can begin using the color system. 


omm To load the color system software from within another program, include the 
ae Lisp form: 
a (load-system ‘color :query nil) 


Alternatively, you can load the color demonstration software as described in 
Appendix C. This ensures that the color software is loaded. In addition, loading 
any of the auxiliary systems automatically causes the color system software to 
be loaded if it is not already loaded. 


os Creating Color Screens 
| Creating a color screen should normally be done only once. Most of the time, 
— programs should use color:find-color-screen to locate a screen that has al- 


ready been created. To create a new color screen, use color:create-color- 
screen, which constructs a menu of likely choices. If the choice you are 
looking for is not there, use the function color:make-color-screen. If the 
color demonstration system has already been loaded, invoking the color 
demonstration (by typing either (color:demo) or :Demo Color at a Lisp Listener) 
causes a color screen to be set up using color:create-color-screen. 


thw 


Creating Color Windows 


You create windows on the color screen in the same way you create windows 
on the black-and-white screen, using tv:make-window, with the following 
considerations: 


> The superior of the window should be a color window or the color 
screen. Programs should call color:find-color-screen to locate an 
appropriate superior. 


A one-pixel-wide border tends to flicker on interlaced color monitors. A 
two-pixel border looks better and is recommended. A long-persistence 
monitor also substantially reduces flicker. 


Bit-save arrays on the color screen consume virtual memory, either 8 or 
32 times as much as on the black-and-white screen. Use them with 
caution. 


Overlapping windows can cause the screen manager to allocate a full-size 
bit-save array. On a 24-bit high-resolution system, the bit-save array is 
5.5 Mbytes. Use overlapping windows with caution. 


Example—Create a color window. 


To create a color window, specify: 


(tv:make-window ‘tv:window 
‘superior (color:find-color-screen) 
‘borders 2 
‘Save-bits nil) 


Messages and Functions for Creating Color Screens 


When a color screen is created, the symbol color:color-screen is set to that 
instance of the new color screen. If you try to create or expose a screen and it 
does not work, see Appendix A—“‘In Case of Trouble.” 


The following functions create color screens of various types. 
WARNING: Do not attempt to make a screen that is at a different bandwidth than your monitor 
can handle. For example, do not make a high-resolution screen when a low-resolution monitor ts 


connected to your system. This can damage the monitor. If you do make a screen that ts the 
wrong bandwidth, turn off the monitor! 
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color:create-color-screen Function 
Presents a list of likely screen types for each color controller. create-color- 
screen accepts the following keyword arguments: 


:controller-types (typel type2.. .) 

:not-controller-types (typel type2.. .) 

:paddle-card-types (typel type2.. .) 

:not-paddle-card-types (typel type2.. .) 

:controller-predicate 

:frame-grabbers (t-nil-or-:only) 
The keyword :controller-types is used to pass a list that represents the 
color controller types that are to be considered by the function. The key- 
word :not-controller-types is used to specify a list of controller types 
that are not to be considered by the program. The controller types passed 


as the argument to these keywords can consist of one or more of the 
following: 


:Standard 

:second-standard 

:frame-grabber 

:cad-buffer 

:cad-buffer-ii 
:paddle-card-types and :not-paddle-card-types function the same way 
but specify the paddle cards required or prohibited by the function. The 


following table lists the valid arguments representing the paddle card types, 
and pairs them with the appropriate color controller: 


Paddle Card Types Color Controller 
:hires-paddle :Standard or :second-standard 
:chroma-hires-paddle :Standard or :second-standard 
:broadcast-paddle :Standard or :second-standard 
:cad-buffer-paddle :cad-buffer 
:cad-buffer-ii-paddle :cad-buffer-ii 
:frame-grabber-paddle :frame-grabber 


Messages and Functions for Creating Color Screens 
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:controller-predicate This keyword provides another filter on the 
types of controllers to be used, in addition 
to the list passed to :controller-types. If 

a :controller-predicate is used, the value 
should be a function to be called to further 
determine whether a given controller is ac- 
ceptable to the program. 


:frame-grabbers :frame-grabbers has three possible val- 
ues: 


:frame-grabbers t 
Frame grabbers are permitted, along with 
everything else. This is the default. 


:frame-grabbers nil 
Frame grabbers are not considered. 


:frame-grabbers :only 
Only frame grabbers are considered. 


The following is an example of the use of create-color-screen: 


(create-color-screen :controller-types '(:standard) 
‘paddle-card-types '(:hires-paddle :chroma-hires-paddle)) 


This Lisp form presents you with a menu of possible screens you Can create 
on systems that contain a standard controller and either the high-resolution 
or chroma paddle board. On a system that does not contain such hardware, 
you are given a pop-up menu informing you that no color hardware is 
available. 


To determine what color controllers and paddle boards are available on 
your system, evaluate the Lisp form (Color:color-controllers) or see the section 
“Getting Information about the Color System” in this chapter. 


color:find-color-screen Function 
Finds and returns a screen with the specifications you need if such a screen 
already exists, and lets you optionally call color:create-color-screen 
(with a keyword argument list passed to it) if no screen can be found that 
matches your requirements. In addition, it lets you select from more than 
one screen if more than one exists (typically useful only when more than 
One controller exists also). 


veer 


sg | 


The global variable tv:all-the-screens is a list of all active screens, includ- 
ing the black-and-white console. From all screens in tv:all-the-screens, 
find-color-screen selects any screen that is :user-visible, that meets the 
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an 


aS 
aa specifications regarding controller and paddle board type, and that returns 
non-nil from the test performed by the value passed through the :message 
pare keyword. The list resulting from these operations is then handled in the 
— manner defined by the :which keyword, or if no such screen can be found, 
the function color:create-color-screen can optionally be called to create 
such a screen. 
he 
= find-color-screen accepts the following keyword arguments: 
me :controller-types (typel type2.. .) 
— 
pol :not-controller-types (typel type2.. .) 
:paddle-card-types (typel type2. . .) 
— :not-paddle-card-types (typel type2.. .) 
:frame-grabbers (¢-nil-or-:only) 
vet The keyword :controller-types is used to pass a list that represents the | 
Pa color controller types that are to be considered by the function. The key- | 
word :not-controller-types is used to specify a list of controller types || 
that are to be excluded by the function. The controller types passed as the \} 
tin . . iW 
argument to these keywords can consist of one or more of the following: | 
| 
:Standard | 
ne || 
es :second-standard 
:frame-grabber ) 
— :cad-buffer : 
:cad-buffer-ii 
ne | 
tins :paddle-card-types and :not-paddle-card-types function the same way, 
but specify the paddle boards accepted or prohibited by the function. The 
rr following table lists the valid arguments representing the paddle board | 
as types, and pairs them with the appropriate color controller: i 
pn Paddle Card Types Color Controller | 
bu | 
:hires-paddle :Standard or :second-standard : 
— :chroma-hires-paddle :Standard or :second-standard 
= :broadcast-paddle :Standard or :second-standard | 
: :cad-buffer-paddle :cad-buffer | 
= .cad-buffer-ii-paddle :cad-buffer-ii 
:frame-grabber-paddle :frame-grabber || 
Vn \ 
Vn 9 Messages and Functions for Creating Color Screens | 
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:frame-grabbers 


:message 


As for create-color-screen, there are 
three possible values for :frame-grabbers: 


:frame-grabbers t 
Frame grabber screens are permitted, along 
with everything else. This is the default. 


:frame-grabbers nil 
Frame grabber screens are not considered. 


:frame-grabbers :only 
Only frame grabber screens are considered. 


The :message keyword gives you the op- 
tion of further filtering screens. If you do 
not specify a value for :message, it checks 
to see if the screen returns a property of 
:color when the screen is sent the message 
:svideo (the basic way of determining a 
color screen). 


If your program has more exacting requirements about the type of screen 
on which it can be run and if you have written a function or a message that 
checks screens against this requirement, you can pass the function or mes- 
sage to the :message keyword as follows: 


A function 


A message 


A message and a list 
of arguments 


:create-p f-or-nil 
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The named function is called, with 
the screen found by find-color- 
screen passed as the function’s 
argument. 


Sent to the screen, if it handles the 
message. 


Sent to the screen, if it handles the 
message; the list of arguments is 
passed at the same time. 


If :create-p is t and no screens are found 
that match the values returned from 
:message, create-color-screen is called. 
If this is the case, the value of :create- 
options is used as the keyword argument 
list to create-color-screen. Default for 
:create-p is nil. 


i 


bare :create-options If find-color-screen does not find a color 

screen that matches the specifications given 
pi it and if :create-p is t, the function create- | 
— color-screen is called with the value of 
:create-options as its keyword argument | 
list. The value of :create-options must be 


a list. 
:which Based on the list obtained through the vari- | 

— ous filters heretofore described, the :which 
mes keyword determines how the final screen 

selections: to #be «made. < ne value. or 
at :which can be one of the following: 
a :all 

Returns the list of all screens that meet the 
i requirements, or nil if there are no such 


screens. In most cases, the list contains one 
screen or nil. | : 


— :choose | 

Pops up a menu listing the screens that 
é meet the requirements. If there is only one 
screen, that screen is returned. This is the 
default value. | 


= :default 
ne Automatically chooses mouse-sheet or 
default-screen, if they are among the pos- | 
um sible color screens. Setting the value of 
ons :default to a fixnum chooses that screen 
among the choices (1 = first screen on the 
un list). 
ae :error-p Determines whether the function causes an 
error or simply returns nil if no screen is | 
vat found. Default is t (cause an error). 
color:make-color-screen &rest keywords Function | 
— Produces a tv:make-window form to execute. Because make-color- | 
inl screen cannot derive all the information it needs from the hardware (for 
example, the type of video to produce and the type of monitor to use), you 
ai must always specify a color controller, a sync program, and a screen type ' 
ih and size. The keywords are processed from left to right, so the last occur- | 
rence of a keyword is the value used. Any other keywords are passed on to | 
- tv:make-window. | 
ae | i} 
Lis 
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In the functions find-color-screen, create-color-screen, and make- 
color-screen, the issue of which color controller to use is meaningful only 
in very specific cases. These cases include the following: 


a If you are writing a program that might be run on different color systems at 
your site, each of which might have a different type of color controller, you 
can use the :controller-types and :not-controller-types keywords to 
specify lists of acceptable and unacceptable (respectively) controller types 
for use by that program. 


. For example, if your site has some systems that use an NTSC controller and 
other systems that use a high-resolution controller, you can use the :not- 
controller-types keyword to specify that a program that requires a high- 
resolution controller cannot be run on one of the NTSC systems. 


If you have a system that has more than one controller physically located in 
the backplane, you can use :controller-types to include the controllers 
that your program accepts, and :not-controller-types to exclude the con- 
trollers that your program does not accept. 


ATWO ei 0 apt I ae dae ie, 


For example, if your system contains both an NTSC controller and a high- 
resolution controller, you can use the :not-controller-types keyword in 
the function create-color-screen (or in the :create-options keyword of 
the function find-color-screen) to specify that a program that requires a 
high-resolution controller cannot be run on a screen created for the NTSC 
controller. 


; make-color-screen is most useful if you have numerous color controllers 
in the same system or numerous system configurations in the same site for 
which you need to design common software. See Chapter 7—*Color Sys- 
tem Tutorial” for examples of the recommended ways to set up color 
screens and windows. 


The keywords can be: 


. a 
* >. . ’ ¥ 
Fn acacia etc erro Sd atl nei Rem eag itee Ir eae 


:controller controller-type Specifies the type of color controller cur- 
rently used in the system. Should be one of 
the=types declared inwthne. Keyword 
:controller-types. 


If you have two standard color controllers, 
you must label one of them :second- 
standard so that you can use the second 
color controller. For example: 


neg he preg neramprt 


[eh fae 


(make-color-screen :setup :standard :controller :second-standara) 
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a e e 
— In this example, the :setup keyword speci- 
fies the type of controller (in this case, 
pore :Standard) to use, and the :second- 
— | standard keyword specifies which of the 
two controllers to use for making this 
a screen. 
v0 
.— :backplane-slot number Specifies the number of a backplane slot 


containing a controller of the specified 

type. For example, if you have two :cad- 

buffer controllers, in slots 6 and 7, you can 

type the following form to indicate which 
controller to use. 


(make-color-screen :controller :cad-buffer :backplane-slot 7) 


:paddle-card paddle-card-type 

Specifies the type of paddle board currently | 
= used in the system. Should be one of the 
vw types declared in :paddle-card-types. | 


:controller-types (typel type2.. .) 

:not-controller-types (typel type2.. .) | 
The keyword :controller-types is used to | 
pass a list that represents the color control- 

—— ler types that are to be considered by the | 

— program. If the controller in the system is 

not one of the types specified in this list | 

(only applicable when a list is specified), no | 

<a color screen is made. The keyword :not- | 

controller-types is used to specify a list of | 
controller types that are not to be consid- 
ab ered by the program. The controller types 

passed as the argument to these keywords 
ae can consist of one or more of the following: 


na | 
oS :standard 
:second-standard 
be :frame-grabber 
- :cad-buffer 
' :cad-buffer-ii 
rn 
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:paddle-card-types (type! type2. . .) 

:not-paddle-card-types (typel type2. . .) 
:paddle-card-types and :not-paddle- 
card-types function the same way as 
:controller-types and :not-controller- 
types, but specify the paddle boards re- 
quired or prohibited by the program. The 
following table lists the valid arguments rep- 
resenting the paddle board types, and pairs 
them with the appropriate color controller: 


Fee rl 


Paddle Board Types Color Controller 
:hires-paddle :standard or :second-standard F 
:chroma-hires-paddle :standard or :second-standard 
:broadcast-paddle :standard or :second-standard F 
:cad-buffer-paddle :cad-buffer 
:cad-buffer-ii-paddle :cad-buffer-ii Z 
:-frame-grabber-paddle :frame-grabber 
If you have one color controller, you can ignore all of the issues regarding E 
multiple controllers. 
:return-spec Returns the :make-window form rather 
than executing it. Used to debug the screen 
setup. The default is nil. 


:dont-check-hardware Creates a screen without having the actual 
hardware present. It is impossible to expose 
4 screen unless the hardware is present. The 
default is nil. 


:no-setq Specifies ‘hat the symbol color:color- 
screen is not set to that instance of the new i 
color screen. The default is nil. | 


:setup option Specifies the color controller, if there is nil 
more than one. Most systems only have ; 

one, so it is the default. option can be any 

of the following: Z 
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:Standard 
Specifies a high-resolution controller oper- 
ating at high resolution (1280 x 1024). 


:ntsc 

Specifies a high-resolution or NTSC- 
resolution controller operating at NTSC res- 
olution. 


:genlock 

Specifies a high-resolution or NTSC- 
resolution controller operating at NTSC res- 
olution with a genlock option. 


:cad-buffer 
Specifies a CAD buffer operating at 1024 x 
1024 resolution. 


:frame-grabber 
Specifies a digitizing frame grabber. 


:pal 

Specifies a high-resolution or broadcast- 
resolution controller, operating at 864 x 582 
resolution at 50 Hz. Uses tv:pai-sync- 
program. 


:pal-like-frame-grabber 

Specifies a high-resolution or broadcast- 
resolution controller operating at 640 x 582 
resolution at 50 Hz. This video format has 
the same aspect ratio and size as frames 
transferred by a digitizing frame grabber 
that extracts PAL format frames. 


:pal-frame-grabber 

Specifies a digitizing frame grabber that uses 
tv:pal-frame-grabber-sync-program to 
extract frames from PAL format frames. 


The following keywords override the :setup defaults: 


shame 


:width 


Specifies a string to be used as the screen 
name. The default is a descriptive screen 
name. 


Specifies the screen width in pixels by a 
multiple of 32. 
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:Sync-program 


Specifies the screen height in pixels by a 
multiple of 32. Must not be greater than 
1024. 


The product of width x height must not be 
greater than the physical memory available 
fort Ne> screen Lore xampler times mic he 
resolution color memory has 2 Mbytes of 
physical memory, so its maximum screen is 
2048 x 1024 with a maximum of 1024 lines. 


Specifies a sync program to use to control 
the video. Normally implied by the control- 
ler. Sync programs are loaded from color- 
:Sync;*.bin. The default is high resolution 
for the high-resolution color controller. The 
sync program’s resolution normally implies 
the screen size. Sync programs specify de- 
faults for width, height, interlace, and pixel 
width. For more information on creating a 
screen with a nondefault or standard sync 
program or how to create your Own sync 
program, see Appendix A. 


WARNING: You can destroy a monitor if you load an inappropriate sync program and leave it 


on too long. If the monitor is not syncing to the video, turn it off. 


:bits-per-pixel 


:controller 


:base-flavor 


:property-list 


interlace 


2 + Color Window System 


Specifies bits per pixel in multiples of 8. 
Normally implied by the number of mem- 
ory boards, but you can specify a smaller 
size than the hardware permits. 


Specifies the controller. Normally implied 
by :setup. Values can be :standard, :cad- 
buffer, or :frame-grabber. 


Specifies the type of window to make. Nor- 
mally implied by the controller. 


Specifies the entries to put on the screen’s 
property list. 


Specifies whether the screen is in interlaced 
or noninterlaced mode. This is normally im- 
plied by the sync program. 
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:pixel-width Allows you to specify an integer to use for 
the pixel width. This is normally implied by 
the sync program. 


:expose-p Specifies whether or not to expose the 
screen. The default is nil—not exposed. 


:paddle-card Specifies which paddle boards are attached 
to the controller. Values can be :genlock, 
shires-paddle, :chroma-hires-paddle, 
:broadcast-paddle, :cad-buffer-paddle, 
:cad-buffer-ii, or :frame-grabber- 
paddle. 


Note: It should not be necessary to specify the :controller or :paddle- 
card keywords, because they are usually implied by the controller. 


color:demo-window optional screen Function 
This function is used by color:demo to find a suitable color demo win- 
dow. It first finds (or creates) a suitable color screen, then finds (or creates) a 
full-sized color demo window on that screen. 


screen can be specified as t to force invocation of the screen-creation menu. 


It should also be noted that loading only the first file in the color demon- 
stration system loads simple test patterns. If you do not want to wait for 
everything to load, load only the file color:demo;test-patterns. 


Getting Information about the Color System 


Several functions are available for use in getting information about the color 


= system. 

color-controllers Function 
Returns a list of controller specifications, each of which is a list of four 

ma elements: controller type, backplane slot, a list of memory slots, and a list 


of paddle boards. For example: 


ae ((:cad-buffer 6 nil (:cad-buffer-paddle)) 
— (:second-standard 5 (38 0) (:chroma-hires-paddle))) 


When more than one color controller is present, the notion of “the color 
i controller” is ambiguous, and various functions used to create or manipu- 
os late a color screen need to take this into account when specifying functions 
specific to a certain type of controller. For details of how the software speci- 
fies which color controller to use, see the functions color:create-color- 
screen and color:find-color-screen in this chapter. For details of the 
various color controllers, see “Color System Hardware Features.” 


Le Getting Information about the Color System 
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Function 


color:color-resources-string 
Returns a string describing the color resources available from the present 
hardware configuration. For example, a system with two color memory 
boards and a standard color controller returns the string “16-bit Standard 
Color.’ The FINGER utility uses this function to report system resources. 


color:color-system-description Function 
Returns three values for each color controller present: the type of color 
controller, the number of color memory boards, and a list of paddle card 
types found in the current system. 


Correcting Simple Problems on the Color Screen 


When you first start using the color system, you might encounter some com- 
mon problems that cause the screen to react in a manner that you did not ex- 
pect. If the pictures on your color screen do not look the way you thought they 
would, that is, if the colors are vastly wrong or the image size is not what you 
intended, check this section for the Lisp forms that correct what you might be 
experiencing. 

If the picture does not appear, be sure you have sent it to the exposed screen. 
Several screens can be made on the same piece of color hardware, but only one 
screen can be exposed at a time. When a new screen is sent an :expose mes- 
sage, any screen currently exposed is automatically deexposed and deactivated 
before the new screen is exposed. Activating a new screen can also change the 
programmable sync generator, resolution, or other software-configurable fea- 
tures of the color system. You can expose a screen either by using the System 
menu or sending the message: 


(send your-window :expose) 
If the colors are far off the mark, you could have one of several problems. To 
begin with, the color map might have been left with nonstandard values as the 


result of some operation that manipulated it. To return the color map to the 
default settings, type the Lisp form: 


(send color:color-screen :standardize-color-map) 


Another likely problem is that the map mode is set for the wrong type of color 
system, that is, a 24-bit color system might be set in 8-bit map mode. To verify 


- that the correct map mode is being used, evaluate the form: 


(send color:color-screen :set-map-mode :24-bit 0 0) 
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Or to set the map mode for an 8-bit system: 


(send color:color-screen :set-map-mode :8-bit 0 0) 


In addition, the monitor might have been set in reverse video mode at some 
time. The color screen message :set-bow-mode determines the black-on-white 
mode of text on the screen. For black-and-white screens, the default value is t; 
for color screens that use the default condition of white letters on a black back- 
ground, the value that uses the default color maps is nil. 


(send color:color-screen :set-bow-mode nil) 


This message replaces every entry in the color map with a complementary en- 
me try. The effect is that every color flips with its complementary color, so black 
and white, red and cyan, and so on are paired. The messages that choose colors 
(such as :compute-color-alu) do not know about :set-bow-mode and there- 
fore are not affected by it. The messages that report colors (such as :rgb-for- 
color, and :flonum-rgb-for-color) inspect the actual color map, so they are 
affected by :set-bow-mode. 


we If the images do not appear or are of the wrong size, initialize the pan and 
zoom. If some program has left the pan and zoom set to some nondefault value, 
you might not be able to make out the image. To correct this error, evaluate the 
Lisp form: 


(send color:color-screen :set-pan-and-zoom 0 0 0 0) 


This ensures that the software pan and zoom is initialized. You can also ensure 
this by typing FUNCTION Z. 


ve If more than one problem is present, initialize the hardware. Normally, creating 
a screen initializes the color system hardware. But, if necessary, the hardware 
can be reset to its proper initial configuration with the following Lisp form: 


(send color:color-screen :setup-hardware) 


: 


For more information about problems you might encounter, see Appendix A— 
“In Case of Trouble.’ 
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— 3 
= Color Maps 


All color screens have a color map, or color lookup table, to translate pixel data | 
eh to actual video color data. The way the color map performs this translation var- 
ies for pseudo-color and direct color systems: | 


wi On a pseudo-color system, one 8-bit pixel is fed to all three color maps. In | 
— this mode, only 256 colors are available at any time, and the current color 
map contains a palette of 256 colors. The broadcast-resolution system has a 
1m 12-bit mode that behaves similarly, with a palette of 4096 colors. (See 
ae HQUre 513) 


On a direct color system, 8 bits each of red, green, and blue pixel data are 
‘it independently translated by the red, green, and blue color maps. In this 
mode, the color maps are typically simple intensity ramps. (See figure 3.2.) 


i} 
Color Map Segments 

The color map contains several segments, only one of which actually drives the | 

nn video at the moment. Four color map segments (numbered O through 3) are | | 
ais implemented in hardware in a high-resolution system. Sixteen color map seg- | 
ments (numbered 0 through 15) are implemented in hardware in a broadcast- 

ow resolution system, and one color map is implemented in hardware in a digitizing | 
ail frame grabber system and a CAD buffer system. On the frame grabber and CAD | 


buffer, the software emulates eight hardware color map segments. 


remit The map segment that is driving the video is called the primary color map seg- 
| ment and is specified with the message :set-map-segment-number 7, where | 
Be n is an integer in the applicable range for the particular hardware configuration. 
ie The message :map-segment-number returns the number of the current pri- 
mary color map segment (the number of the segment currently used to drive 
the video); the default primary color map segment is 0. Each map segment is 
aa made up of a number of slots, or index entries; each slot contains specifications | 
for the red, green, or blue intensity to be associated with each pixel value. The | 
specifications vary with the hardware configuration and need not be the same 
aa in each color map segment. This means that you can change the color of ob- 
re jects on the screen by changing the primary color map segment number, if you Hl 
have different color values in different segments. 
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Figure 3.2 24-bit color mapping 
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Managing Color Maps 


This section describes several color map conventions that provide a default map 
management strategy. You do not need to adhere strictly to these conventions, 
but following them can save you from experiencing problems later if you ever 
transfer your color software to another hardware configuration. This is espe- 
cially important if your site already has more than one type of color system 
hardware. 


As stated in the preceding section, each color screen uses color map segment 0 
as its default primary color map segment. Applications that need special color 
maps use map segments | through 7, where 7 is the number of color map seg- 
ments available, as determined by the hardware configuration. 


Direct color screens (24-bit pixels) initialize their primary map segment to a 
simple ramp. A simple linear relationship exists between pixel values and 
perceived colors. Programs that expect to run only on direct color systems 
usually use this linear relationship freely. 


By default, the ramp contains 256 slots, where slot 0 in all map segments 
contains black and slot 255 in all map segments contains white. The color 
demonstration system uses this map strategy. You can modify the ramp to have 
fewer colors. The remaining slots of the color map are unused and are therefore 
available for custom map design. 


For pseudo-color systems (8-bit pixels) or applications where overlays are in 


use, color map management is not as easy. Because only a limited set (usually 
256) of colors is available, the windows on the screen have to share the same set 
of colors. Pseudo-color screens initialize their primary map segment to a stand- 
ard palette of colors. By default, the ramps contain six shades of each primary 
(red, green, and blue) in every combination. Therefore the palette contains a 
total of 6*6*6 = 216 colors, in slots 1-216. Slots 217-254 contain complemen- 
tary colors, so complementing (XORing) those slot entries produces visible 
lines. 


Other map segments initially contain the same color palette but can be changed 
by any program that needs special color maps. Programs that need to temporar- 
ily set up their own map segment usually use color map segment 1. Such pro- 
grams should use unwind-protect around the portion that assigns the screen’s 
map segment number to make sure the color map segment number assignment 
is changed back to O, the default segment. Most programs in the color 
demonstration system use the default color palette. 

Another common way to set up a color palette is simply to allocate colors start- 
ing from slot 1, map segment 1. The Spheres Demo program in the color 
demonstration system uses this strategy to allocate the colors for its shaded 
spheres. 
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All color screens have an auxiliary instance, called a map manager, that knows 
the structure of the color maps and can translate requests for colors into appro- 
priate color ALUs. The map manager is an important instance that will be ex- 
panded in later releases. 


Using pseudo-color data on a direct color system is done by creating an 8-bit 
screen rather than a 24-bit screen. The other memory boards are simply ig- 
nored. The disadvantage of this method is that the unused memory is inacces- 
sible. The advantage is that the system operates like a real 8-bit system, indistin- 
guishable from one where only 8 bits are available. A second advantage is that 
bit-arrays are really 8 bits rather than 32 bits, which reduces virtual memory 
consumption and paging. See Chapter 2—“Color Window System” for details 
about creating color screens. 


You can set a 24-bit screen into 8-bit mode. This technique is used to load an 
8-bit image quickly, reload a color map quickly, color an 8-bit grayscale image, 
or make one 8-bit system compatible with another 8-bit system. All 24 bits are 
still available, but only 8 bits at a time are used to generate video. Most pro- 
grams do not notice the extra bits. 


If you construct ALUs carefully, you can use all three 8-bit sections indepen- 
dently. For example, you can implement double or triple buffering. Double 
buffering is a technique in which the system computes the next frame in a se- 
quence while it displays another. Triple buffering is when the system computes 
the next frame in a sequence while it displays another and then erases the first 
frame when it is done computing the second. 


It is also possible to view 24-bit images 8 bits at a time. For example, you can 
put a simple ramp of grays in the color maps and look at the red, green, and 
blue data alternately. Or you can translate RGB data to YIQ and use the intensity 
data as a black-and-white display. 


You can remap the 8-bit pixels to 24 bits by playing them back through their 
usual color maps and putting the resulting values into the 24-bit pixel memory. 
This technique is used by the IMAN system when playing back 8-bit images on a 
24-bit system. 


Using direct color data on a pseudo-color system is done using data compres- 
sion techniques. The IMAN system implements several data compression tech- 
niques that represent 24-bit images using 8 bits per pixel. These techniques 
require preprocessing of 3-10 minutes per frame, but once processed, images 


- can be played back as fast as “‘natural’’ 8-bit images. 


For computer-generated colors, you can simply approximate the desired color 
with one from a palette. 


Managing Color Maps 


Overlay Effects 


Special translations make it possible to create special effects with the video 
using color maps. These translations are called overlays. Overlays are of two 


types. 


Transparent overlay uses some number of bits of pixel data to select which 
color map segment to use, while the rest of the bits select which color to use in 
that map segment. This type of translation gives a transparent effect. For exam- 
ple, color map segment 0 can be an ordinary linear ramp, while the other color 
map segments can “wash” the image with a certain hue. For example, to create 
the effect of looking at part of an image through a red filter, you might use a 
“redder” version of the color used in that part of the image. 


Replacement overlay uses some number of bits of pixel data to specify a value 
to use in some other color map segment, unless the overlay bits are all Os. This 
type of translation makes it possible to insert blocks of text or graphics to re- 
place the normal pixel data. 


The difference between transparent and replacement overlay is that when you 
use transparent overlay, all the pixel data always participate in the color selec- 
tion, so the overlay color is partially a function of the underlying color. When 
you use replacement overlay, the pixel data separate into two parts and one or 
the other selects the color. The overlay color, if it is used, is unrelated to the 
underlying color. 


The chroma and broadcast-resolution systems allow you to use the high 8-bit 
field of the 32-bit pixel value as another image to alter the picture. This 8-bit 
field is called an overlay plane because it appears to “lie over” the 24-bit image 
underneath it. This technique is called hardware overlay. 


Any references to map modes that include transparent or replacement pertain to 
hardware options that use more than the minimum 8 bits of pixel data. 


You can simulate transparent and replacement overlays without special hard- 
ware support. This is done by using the color map (either on an 8-bit system or 
4a 24-bit system in 8-bit mode) to arrange for the bits in the pixel to be inter- 
preted in a bit-weighted scheme. Techniques for this are detailed in Chapter 7— 
“Color System Tutorial.” One disadvantage of this is that, as is apparent from the 
example in the tutorial, you run out of color map entry slots very quickly. 


The Finger of God program in the color demonstration system uses a simple 
software implementation of transparent overlays. 
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= Gamma Correction 
The eye’s response to light is not linear, and the amount of light output by color 
nw monitors is not a simple multiple of the video signal’s intensity. A process called 
a gamma correction is used to correct the brightness values to appear linear to 
the eye. 
—| Most monitors adjust a nonlinear signal source by varying the brightness lin- 
early. Therefore, the color maps map the digital color values (usually 0-255) 
rae directly into video values, with no gamma correction. However, if the amount | 
— of gamma correction performed by the monitor is inadequate, you can write a | 
| 
custom color map to perform gamma correction. | 
nite The Edit Color Map program in the color demonstration system demonstrates a 
boom simple version of this. | 
| 
se i 
— Color Map Messages 
A color map translates pixel data to actual video color data. The way the color | 
Ee map performs this translation varies with the hardware configuration. ] 
ae | : Le ; i | 
wow When dealing with color maps, it is useful to consider the following types of i 
objects. HT 
vl , ! | 
bow Color map is the term used to describe the contents of the color map in 
hardware. One selected segment of this map drives the video; pixel data are I 
ofl interpreted as index entries in the color map segment. \\] 


There are also objects called color map images. There is always at least 

one color map image that the system maintains automatically; this color | 
rie map image represents the actual state of the hardware color map. The | 
importance of this image is that it automatically reflects any changes made \\ 
to the color map, and is therefore useful for determining the exact status of | 
rie the hardware color map at any time. The message :color-map-image re- 
ai turns this object. 


In addition, you can create any number of color map images that are not 

— explicitly associated with the color hardware. You create these images using the 
message :make-color-map-image, most likely for the purpose of cycling 

Ss through several color maps for making pseudo-animation effects. These images 

ata do not exist unless you create them. You can affect these color map images in 

_ several ways: 


45 > Copy the image you created into the hardware for the purpose of chang- } 

eres ing the color of objects on the screen (using the message :new-color- | 
map). 

oa 
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> Make one of these image objects act as the color map image that repre- 
sents the state of the hardware color maps (using the message :set- 
color-map-image). 


Note that :set-color-map-image does not affect the contents of the hardware 
map, the contents of the color map image that reflected the hardware map be- 
fore sending this message, or the contents of the new color map image that has 
just been made to reflect the contents of the hardware. All that :set-color- 
map-image does is change the object used to reflect changes to the color map; 
instead of storing changes in the color map image created by the system, further 
changes are now stored in one of the color map images you created. 


You can send the following messages to the color screen: 


:color-map Message 
Returns the actual color map, or nil if the screen does not have one. Pro- 
grams should use this message or :color-map-description as the test to 
see whether a screen has a color map. If the result is nil, programs should 
not use any of the other color map messages. 


For all current screens that do have a color map, the value of :color-map is 
an array, though the exact type, size, and contents vary depending on the 
hardware. It is recommended that you manipulate color maps only through 
the interface documented here, rather than using array primitives. 


Read and write operations concerning the hardware color map synchronize 
with the vertical retrace of the screen and might take up to a full frame time. 
For that reason, and because it is aesthetically pleasing to change color 
maps rapidly, it is recommended that you use the color map image for all 
color map operations and then update the hardware from this color map 
image. 


:color-map-description Message 
Returns four values if the screen has a color map. Returns nil if the screen 
does not have a color map. This message is supported by all screens. 


The four values are: 


size Returns the number of map slots in each 
color map segment, which corresponds to 
the number of pixel bits used to index into 
it. For most of the hardware, this is 256, but 
in some overlay modes this is not the case. 


Note: This number can change as a function of the map mode as well as 
the hardware configuration. 
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number-of-segments 


map-mode 


overlay-type 


Returns the number of map segments that 
are available for a particular hardware con- 
figuration. 


Returns :dependent when one copy of the 
pixel data is sent to all three (red, green, 
blue) channels, as is the case with 8-bit sys- 
tems. 


Returns :independent if three indepen- 
dent fields within the pixel are driving the 
three channels, as is the case with 24-bit 
systems. 


map-mode reflects the current hardware 
State. 


A change to map-mode also affects the 
RGB values of an ALU. The color screen 
messages :rgb-for-color and :flonum- 
rgb-for-color return the RGB values of an 
ALU. 


Returns the type of color map overlay in 
effect. The three types are: 


:none 
No overlays. This is the default. 


:transparent 
Transparent overlays are in effect. 


:sreplacement 
Replacement overlays are in effect. 


Note: The CAD buffer overlay types are distinct and are described in the 
section “CAD Buffer Messages’ in Chapter 6— ‘Additional Color System 


Features.’ 


:overlay-description &optional control-image Message 
Returns three values describing the overlays in effect for control image. 
control-image is a control image, or defaults to the hardware control image. 


The three values are: 


overlay-byte-position 


overlay-byte-size 


Color Map Messages 


Returns the number of bits to shift (the posi- 
tion field of a byte specifier) to reach the 
overlay field within a pixel. 


Returns the size in bits (the size field of a 
byte specifier) of the overlay field. 
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overlay-type Returns the type of color map overlays in 
effect. The three types are: 


:none 
No overlays. This is the default. 


:transparent 
Transparent overlays are in effect. 


:replacement 
Replacement overlays are in effect. 


control-image should be one of the following: 


A control image, returned by the :control, :control-image, or :make- 
control-image messages 


t, indicating the default control image 


nil, indicating the actual control hardware 


:default-map-mode Message 


Returns the default map mode for the current hardware configuration. This 
value is not changed by changing the map mode in use (accomplished with 
the :set-map-mode message), but is dependent on the type of screen cre- 
ated. 


:map-modes Message 


Returns two values. The first is a list of symbols describing the map modes 
available; the second is the number of color map segments that exist in the 
hardware. This is not necessarily as large as the value returned by :color- 
map-description. 


The following modes are supported by some hardware configurations; to 
find out which hardware configurations support what features, see 
Chapter 9—‘‘Color Hardware Options.” 


:8-bit 8-bit-per-pixel mode, where one 8-bit pixel 
drives all three color channels. Supported 
on the high-resolution, chroma, and 
broadcast-resolution systems. 


:8-bit-replacement-overlay 

:8-bit-transparent-overlay 8-bit-per-pixel modes, where one 8-bit pixel 
drives all three color channels and some 
additional bits control overlay selection. 
Supported on the chroma and broadcast- 
resolution systems. 
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—_ :12-bit One 12-bit sample drives all three video 
channels. Supported on the broadcast- 

- resolution system. 

| 

- :24-bit 24-bit-per-pixel mode, where three inde- 


pendent 8-bit color channels control the 
video. Supported on the high-resolution, 
chroma, and broadcast-resolution systems. 


:24-bit-replacement-overlay 


a :24-bit-transparent-overlay 
24-bit-per-pixel modes, where three inde- 
_ pendent 8-bit color channels control the 
—_— video, and some additional bits control 
overlay selection. Supported on the chroma 
— and broadcast-resolution systems. 
, :map-mode optional control-image Message | 


Returns six values describing the operation of the color map in the current 
control image. The six values are: || 


mode-name The name Omiicanoade stnateissonesoOh tne 
values returned by the message :map- 
modes. 

segment-number The map segment that is the current pri- 


mary source for video data. 


pixel-position The position of the pixel data driving the 
oF primary source. (The position field of a byte 
specifier.) 


pixel-size The size of the field within each pixel that q 
drives the primary source. (The size field of | 
eu a byte specifier, implied by mode name.) 


pes overlay-position The position of the pixel data driving the 
, overlay, or O if none. (The position field of a 
byte specifier. ) 


_— overlay-size The size of the field within each pixel that i| 
drives the overlay source. (The size field of | 
a byte specifier, implied by mode name.) 


Buffer Messages” in Chapter 6—“Additional Color System Features.” 
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:set-map-mode mode-name segment-number Message 
pixel-position overlay-position 

Sets up the color screen in a specific mode. mode-name, segment-number, 

pixel-position, and overlay-position are values that could have been re- 

turned by :map-mode. :set-map-mode is the recommended way to set 

up the color screen in a specific mode because it works the same for any 

screen that supports the mode you specify. 


:pixel-positions &optional control-image Message 


Returns two values. The first is a list of the valid pixel-position arguments 
for the main pixel field for the control image in its current mode. The 
contents of this list correspond to the valid values for the third argument for 
:set-map-mode. 


The second value is similar but returns the position of the overlay plane. 
Overlay planes are supported on the chroma and broadcast-resolution sys- 
tems. (It returns 0 if no overlays are in effect.) This corresponds to the valid 
values as the fourth argument of :set-map-mode. 


For example, on a broadcast-resolution system when :map-mode returns 
:8-bit-transparent-overlay, :pixel-positions returns: 


(values '(0 8 16 24) '(24 28)) 


:color-map-image Message 


Returns an object that is a software copy (an array, really) of the actual 
hardware color map. Any changes you make in the hardware color map are 
also copied into this image to keep it in sync with changes to the actual 
hardware. Changes made to this color map image are copied to the hard- 
ware only when asked for explicitly (see the message :new-color-map). 
This lets you change the color map image until it is in the state you want to 
use, and then write the entire image into the hardware color map in one 
operation. You can also create additional color map images for your own 
use (see the message :make-color-map-image). 


:set-color-map-image new-image Message 


Specifies the object used to reflect changes to the hardware color map; 
instead of storing changes in the color map image created by the system, 
further changes are now stored in one of the color map images you created 
(specifically in the one passed to :set-color-map-image). Does not change 
the hardware state, the current contents of the old color map image, or the 
contents of the new color map image. That is, the array object passed in 
new-image is stored in the screen’s instance variable, but the hardware 
color map is not updated with its contents. 
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:make-color-map-image Message 
Creates a new color map image. For programs that need their own color 
map and applications where it is not desirable to permit them to recompute 
one, use :make-color-map-image to create a private color map. For ex- 
ample: 


(defvar *personal-color-map-image* 
(send color:color-screen :make-color-map-image)) 


After evaluating this form, the variable * personal-color-map-image’* is 
available for use as a color map image. The initial contents of the new image 
are unspecified. You can use :write-color-map-image to specify the con- 
tents of individual slots of your new color map image, or the message :init- 
managed-color-map to set up a default palette in the form that :com- 
pute-color-alu expects. 


:init-color-map message-name Init Option 
Specifies the message that the screen sends to itself to initialize its color 
maps. The default is a message appropriate for the kind of screen in ques- 
tion. (See the message :initialize-color-map.) 


:init-color-map Message 
Returns the message that the screen sends to itself to initialize its color maps 
when the message :initialize-color-map is evaluated. The default is a 
message appropriate for the kind of screen in question. 


:Set-init-color-map message-name Message 
Specifies the message that the screen sends to itself to initialize its color 
maps. 

:Standardize-color-map Message 


Initializes the color map image using the message from :init-color-map 
and copies it to the color map. Use this message to return the color map to 
its standard state. This is the message that the color demonstration program 
uses to initialize color maps. 


:initialize-color-map &optional segment-number map Message 
spec-function gamma 
Initializes the optionally specified map to be a ramp of grays; by default, 
map is the color map image used to reflect changes to the hardware. If 
segment-number is nil, all color map segments are initialized. If segment- 
number is specified, it should be a small integer in the valid range for the 
current color map mode. 


Unless map is the real color map (that is, the object returned by the :color- 
map-message), the hardware state is not affected. 
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spec-function is useful only if you wish to design your own algorithm for 
generating color maps. If you have such a function, pass it to the 
:initialize-color-map message and it is called to generate the custom 
color map. 
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gamma is an exponent to be used for gamma correction. 


:init-managed-color-map &optional segment-number map Message 
Initializes map to be a ramp of grays for a direct color system. If segment- 
number is nil, all color map segments are initialized. If segment-number is 
specified, it should be a small integer in the valid range for the current color 
map mode. 
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:new-color-map &optional new-map segment-number Message 
Writes a color map image specified by the argument new-map to the hard- 
ware. If mew-map is nil, the color map image associated with the hardware 
is used. segment-number specifies a color map segment number to write 
one color map segment only. If segment-number is nil, all map segments 
are written. 
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Note: It takes one-fourth of a second for the high-resolution color hard- 
ware to write the complete color map because of pauses to synchronize 
with vertical retrace, so it can be important to specify segment-number to ; 
update only the segment you have changed. d 


:map-segment-number &optional control Message 
Returns the primary color map segment number driving the video. If the 
optional argument control is supplied, it must be a control register image 
(see the section “Control Register Messages” in Chapter 6—“Additional 
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Color System Features”), and the primary color map segment number is 4 | 

read from that control register image instead of the actual hardware. 
:Set-map-segment-number 7 Soptional control Message y 

Sets the primary color map segment driving the video. m must be a number . 


less than the number of physical hardware color map segments available. If 
the optional argument control is supplied, it must be a control register 
image (see the section “Control Register Messages’ in Chapter 6— : 
“Additional Color System Features”), and the primary color map segment 
number is set in that control register image instead of the actual hardware. 


a 
r 
- :default-map-segment-number Message 
Returns the default color map segment number for reading and writing | 
color maps. 3 
E 
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:Set-default-map-segment-number 77 Message 
Sets the default color map segment number for reading and writing color 


maps. | 


Reading and writing a color map requires a segment number, which defaults | 

to the value of the instance variable :default-map-segment-number. | 

a :default-map-segment-number is unrelated to :map-segment- | 
- number. 


Note: For reading and writing slot entries in the color maps, the common | 
format ts that color values are integers in the range O0-1023, where O is 
| 
| 
| 


black and 1025 ts white. This does not imply that those are the values to be 
we found in the color map images, only that this is the interface to them. The 
Ir values might not have the same binary precision as the values in the color 
map images, because the internal formats of the color maps differ due to 
hardware differences. 


Reading or writing a color map also requires a slot number, or map entry 
number, which must be an integer in the appropriate range for the current 
map mode. 


:read-color-map s/ot-number Message 
&optional segment-number 
Returns three integer values that correspond to the red, green, and blue data 
in the hardware color map segment. slot-number specifies the color map 
entry in the current color map segment or in the specified color map seg- 
T ment if the optional segment-number is specified. segment-number must be 
a number between 0 and 3. slot-number must be a number between 0 and 
255. :read-color-map synchronizes with vertical retrace. 


:read-color-map-image s/ot number Message 
&optional segment-number map 

ene Returns three integer values that correspond to the red, green, and blue data 
r for one of the color map images. map defaults to the color map image 
\— . . . . 

associated with the hardware, but can be any color map including the hard- 
ware map. As with :read-color-map, s/ot number must be a number be- 
tween 0 and 255. segment-number, if specified, must be a number between 


O and 3. 
ae :read-managed-map s/ot-number &optional segment-number Message 
— Returns three floating-point values between O and 1.0 that correspond to 


the red, green, and blue data in the hardware color map segment. s/ot- 

number specifies the color map entry in the current color map segment or 

in the specified color map segment if the optional segment-number is speci- 
fied. segment-number must be a number between O and the highest seg- 
ment number permitted by the hardware. 
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:write-color-map s/ot-number red green blue Message 
&optional segment-number 

Writes the red, green, and blue data into the hardware color map segment 
or in the specified color map segment if you specify the optional segment- 
number. slot-number must be a number between 0 and 255. red, green, 
and blue are the red, green, and blue values, respectively; each must be a 
number between 0 and 1023. :write-color-map synchronizes with verti- 
cal retrace. 


:write-color-map-image s/ot number red green blue Message 
&optional segment-number map 
Writes the red, green, and blue data into the hardware color map segment. 
map defaults to the color map image but can be any color map image 
including the hardware map. 


:write-managed-map s/ot-number red green blue Message 
&optional segment-number 
Writes floating-point values representing the red, green, and blue data into 
the hardware color map segment, or in the specified color map segment of 
the map if you specify the optional segment-number. slot-number must be 
a number between 0 and 255. red, green, and blue are the red, green, and 
blue values, respectively; each must be a number between 0 and 1. 


:update-color-map-from-image &optional image Message 
Writes the color map image associated with the hardware into the hardware 
color map, on vertical retrace. image specifies an alternate color map image 
if you do not want to use the default color map. 


:map-manager Message 
Returns the map manager of a color screen. All color screens have an auxil- 
iary instance, called a map manager, that knows the structure of the color 
maps and can translate requests for colors into appropriate fill-data. The 
map manager is an important instance that will be expanded in future re- 


leases. 


:name-color symbol red &rest green blue Message 
Creates a name to be associated with a color specification. You can then 
pass this named color to the ALU, and objects you draw with this ALU 
appear in the color specified with the s:name-color message. 


sname-colors specs Message 
Names a list of colors, where specs is a list of specifications appropriate for 
:name-color. This is a message of color screens. The values for specs are 
the same as the values listed under :compute-color-alu. 
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— :get-color-named symbol Message 
Returns the color specifications for a particular color. This is a message of 
-_ color screens. | 
™ | 
st 


:compute-rgb-data red green blue Message 
This message is used by the message :compute-color-alu and is not par- 


rE ticularly useful directly unless you intend to design your own ALU func- 
= tions. It packs the pixel values returned by :compute-rgb-slots into one 
pixel value, by combining either one value for pseudo-color screens or 

) = three values for direct color screens into one pixel value, which is what is 


actually used. Returns one value for pseudo-color screens or three values 
for direct color screens. red, green, and blue are flonums in the range 0.0 to 
1.0. The values correspond to the color map slots used to represent the 
color. This is a message of color screens and map managers. 


:compute-rgb-slots Message 
Like the preceding message, this is used by :compute-color-alu and is not 
particularly useful in a color program unless you intend to design your own 
ALUs. This message returns the actual color map slots that are used to 
generate a particular color. This is a message of color screens and map 
managers. 


:Set-bow-mode f-o7r-nil Message 
Replaces every entry in the color map with a complementary entry if t, 
returns to the original state if nil. The effect is that every color on the | 

ra screen flips with its complementary color, so black and white, red and cyan, | 

_ and so on are paired. The messages that choose colors (such as :compute- | 

color-alu) do not know about :set-bow-mode and are therefore not af- 

| 


fected by it. The messages that report colors (such as :rgb-for-color and 
:flonum-rgb-for-color) inspect the actual color map, so they are affected 
by :bow-mode. 


:reverse-video-p Message i) 
Returns nil normally or t if the color window displays in reverse video. | 
Reverse video for the color window exchanges the foreground and back- 
ground colors, as defined by char-aluf and erase-aluf. The two reverse- 
video messages simply exchange the colors used as foreground and | 
background colors, unlike :set-bow-mode which complements all colors | 


et 

iat in the map. 
:Set-reverse-video-p Message | 

rr Sets or disables reverse video display for the color window. Reverse video | 

~— for the color window exchanges the foreground and background colors, as | 


defined by char-aluf and erase-aluf. Comparable to the effect of FUNC- 
TION c-C and FUNCTION m-C on black-and-white screens and the mouse docu- 
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mentation line, respectively. Therefore, if the erase-aluf specifies pink and 
the characters are blue, reverse video simply exchanges the foreground and 
background colors rather than generating two new colors corresponding to 
the complement of the existing color choices. 


For color windows that use instance-based ALUs, :reverse-video-p is sim- 
ply a toggle that is set by :set-reverse-video-p. 
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Color ALUs 


This chapter describes how to use color ALUs for drawing operations. 


Basic Concepts 


Three general types of operations use ALUs: 


> Pure drawing operations, such as :draw-line or :draw-filled-in-circle 


> Font-drawing operations, such as :draw-char and :draw-string 


> Bit-copying operations, such as :bitblt and :bitblt-within-sheet 


In system releases prior to 6.0, all these operations permitted an ALU specifica- 
tion, which had to be an integer from O to 15. This integer was interpreted iden- 
tically to the first argument of the function boole, as follows: 


(setf result-pixel (boole alu-code -1 source-pixel)) 


See the document Reference Guide to Symbolics-Lisp for a description of the 
function boole. 


While this method of ALU specification is sufficient for all possible operations 
on a one-bit-per-pixel screen, it does not suffice to specify the operations 
possible on an 8- or 24-bit screen. The color ALU was therefore developed as a 
compatible way to provide all the information needed to specify drawing opera- 
tions on color screens. 


rt 


Note that although the numeric ALU code is still available, and therefore the 
boolean functions can be performed on the four-bit numeric ALU code, it is 
strongly recommended that you refer to the symbolic names of the ALU codes 
as listed in this chapter. 


Color ALUs are instances of the flavor color:general-sc-color-alu or flavors 


— based on it. They have several instance variables, each of which specifies one 
aspect of the drawing operation, for example, the pixel value. The messages 
supported by ALU instances are explained in the section “ALU Functions and 

in Messages’”’ of this chapter. 
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The color ALU capabilities described here are present in the standard software; 
you do not need to load the color software in order to access these ALU func- 
tions. This simplifies writing programs that might be run on the black-and-white 
monitor as well as the color monitor. 


The color ALU capabilities apply to drawing only when invoked by messages to 
a window or screen. It does not work to provide an ALU instance as the ALU 
parameter to a call to the primitive drawing functions or bit-copy operations | 
such as the functions draw-rectangle or bitblt. nay 
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The following aspects are specified by the color ALUs when drawing on a color 
screen: 


Fill-data What numeric value is combined with the pixel’s existing value 
as shown in the composite ALU operation. This attribute is 
represented by the instance variable fill-data. 


Plane-mask What bits in the destination pixel are enabled to be written. A 
1 bit in the mask enables the corresponding bit in color 
memory to be written. The default is to enable all the bits to be 
written, represented by the fixnum -1. This attribute is 
represented by the instance variable plane-mask. 


ALU-code A 4-bit argument to the boole function as shown in the 
composite ALU operation, which controls the bit-by-bit 
combination of the existing value of the destination pixel and 
the fill-data. The default is tv:alu-seta, which simply writes 
the new value and discards the old. This attribute is 
represented by the instance variable alu. 


Array Which of the color screen’s screen arrays are used. Color 
screens have several arrays, which address the color memory 
in different ways. It is sometimes necessary to specify which 
one is to be used in an operation, in which case this instance 
variable must be specified. This attribute is not shown in the 
composite ALU operation because it is usually left to its default 
value, the symbol :default. :default means to use the array 
appropriate for the kind of draw or copy being done. This 
attribute is represented by the instance variable array. 


The default value of both fill-data and plane-mask is -1 (1s in all bits, mean- 
ing write 1s everywhere) so the default ALU operation is identical to the old 
behavior. To use the new fill-data and plane-mask instance variables, you can 
specify them in an instance of an ALU flavor, which is passed in place of the 


4 - Color ALUs 


| 
— 4-bit alu instance variable when sending a message to a window. This applies to 
windows on the black-and-white screen as well as the color screen. fill-data 
— and plane-mask are described in more detail later in this chapter. 
st 


It is no longer appropriate to type-check ALUs by checking that they are inte- 
gers. The protocols for handling instance ALUs are described in the section 
“ALU Functions and Messages” in this chapter. 


The composite operation specified by alu, fill-data, and plane-mask can be 
defined by the following formula: | 


=) (setf result-pixel | 
(let* ((Combined-value (boole alu-code fill-data source-pixel)) 
(changeda-part (logand combined-value plane-mask)) 
(unchanged-part (logand source-pixel (lognot plane-mask)))) 
(logior unchanged-part changed-part))) 


For example, on a 24-bit color system, suppose the pixel to be drawn on con- 
tained the octal value 2525252, and the above formula were invoked with 
plane-mask being 377, fill-data being 3333333, and alu being tv:alu-xor. 
The results would be: 


Combined value would be the bit-wise exclusive-OR of the pixel’s value 
(2525252) and the fill-data (3333333), or 1616161; this would be masked 
by the plane-mask (377) to produce 161 as the changed part. The un- 
changed part would be computed by a logical AND of the complement of 
© the plane-mask (the complement being in this example -400) with the 
Ps pixel’s value (2525252), with 2525000 resulting. These are combined ina | 
logical OR, producing the value 2525161 to store back into the pixel. 


Font Handling Capabilities 


In the past, the actual behavior of drawing characters (:draw-char, :draw- 
string, and so On) with “unusual” ALUs was erratic and likely to be unsatisfac- 
ri tory. The reason for this is that the background raster for the font was also 
a drawn usif® the ALU code and so affected the result. That is, the rectangle 

around the character (sometimes called its “slug’’) was drawn as well as the char- | 
= acter itself. | 
Font operations are now defined for color screens to operate as though only the 
1s in the font affect the result, that is, as though :draw-char individually drew | 
mt each of the 1s in the character. For tv:alu-ior (“write 1s’’), tv:alu-xor (exclu- 
sive or), and tv:alu-andca (“write Os’’) on the black-and-white screen, this is | 
identical to the old behavior. 
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Asa result of this change, the sixteen boolean-drawing functions on the black- 
and-white screen actually behave in only four different ways, corresponding to 
write, erase, complement, and noop, and are consistent with other drawing 
operations. 

On color screens, the sixteen boolean-drawing functions are all distinguishable, 


useful, and behave consistently with other drawing operations. 


Wide Font Protocol 


In releases prior to 6.0, the system automatically created “expanded fonts” as 
necessary. These expanded fonts were merely multibit-per-pixel copies of the 
corresponding 1-bit fonts. Expanded fonts are no longer required and are there- 
fore no longer created. 

The only valid use for a multibit-per-pixel font is to create a multicolored or 
antialiased font. Neither antialiased fonts nor any functions to create them are 
supplied. However, the function make-wide-font might be useful as an exam- 
ple to follow should you decide to write your own code to make antialiased or 
multicolored fonts. 


make-wide-font old-fd expansion mask prop-name Function 
Creates and returns a new font. The name of the new font is created as 
follows: EXP < expansion > -<old-fd>. For example, if old-fd is CPTFONT 
and expansion is 8, the new font’s name is EXP8-CPTFONT. The new font 
has all the attributes of o/d-fd, and each character has the same attributes as 
old-fd. The new font appears in the color specified by mask. The argu- 


ments are: 

old-fd A 1-bit-per-pixel font (the actual font, not the font name). 
expansion The width in bits of the new font. 

mask The pixel value for bits of the new font, usually -1. 
prop-name The property name of the font name of old-fd where this 


font will be stored. 


There is no reason to make a font this way unless you also intend to do some 


other processing of the font's pixel data. In wide fonts where all pixels are either 


0 or mask, you can get exactly the same effect using a standard font and draw- 
ing characters with an ALU of the desired characteristics. 


Making ALU Instances 
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The default ALU flavor is color:general-sc-color-alu. You can Grealenils 
stances of this flavor with make-instance or with the function color:sc-fill- 
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alu. This function is documented in the section “ALU Functions and Messages” 
in this chapter. 


A black-and-white screen has only one bit per pixel, so the only interesting case 
is where the low-order bit of the plane-mask is a 1. On the color screen, with 
8-32 bits per pixel, the plane-mask can be used to protect fields you want to 
leave unchanged. The most common example of this is when you use overlays. 
The color screen messages :map-mode and :overlay-description provide 
information about the hardware overlay capabilities currently in use on a partic- 
ular screen. 


The plane-mask and fill-data instance variables have meaning only in relation 
to the kind of screen on which they are used. This means that there is no such 
thing as ‘‘an ALU instance that means red on all screens.’ The meaning of the 
instance variables of an ALU instance is affected by the kind of screen (1-, 8-, or 
24-bit) and the settings of its color map (if any). Thus, on an 8-bit system, if the 
color map translates the color index 42 to the color orange, that index should 
be written into a pixel to produce that color. In a 24-bit direct color screen, an 
entirely different numeric value is needed. On a black-and-white screen, there is 
no numeric value that produces orange. 


The fill-data instance variable for an ALU object specifies only the pixel value; 
the interpretation as a color is dependent upon the kind and state of the screen 
on which that data are displayed. By convention, fill-data of 0 means black and 
fill-data of -1 means white (although this is conventional, the meaning of fill- 
data is at all times completely determined by the color map of the screen). 


Two different formats specify color, depending on whether the screen is direct 
color or pseudo-color. 


Fill-data on a direct color screen is interpreted as a 24-bit value that contains 
three 8-bit fields, one each for the red, green, and blue color components. For 
example: 


(load-byte x 0 8) gets red 
(load-byte x 8 8) gets green 
(load-byte x 16 8) gets blue 


The individual red, green, and blue fields index separately into the color map. 
(See figure 3.2 in Chapter 3—“‘Color Maps.”) The color the screen actually dis- 
plays depends on the color map setup and the screen’s map modes. For direct 
color screens, the color maps are by default set up with simple ramps of increas- 
ing intensity, so that higher values of each color field specify a more intense 
color. The message :color-map-description returns :independent as its 
third value for a direct color screen. 
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Fill-data on a pseudo-color screen is interpreted as a single 8-bit value. 
Normally, (load-byte x 0 8) gets the color field, but in systems with more than 

8 bits per pixel operating in 8-bit mode, it is possible for the field to be located 
at any 8-bit boundary. The :map-mode and :overlay-description messages 
provide this color screen information. The message :color-map-description 
returns :dependent as its third value for a pseudo-color screen. The 
disadvantage of this arrangement is that there is no intrinsic relationship 
between the fill-data value and the color displayed. (See figure 3.1 in 

Chapter 3—‘‘Color Maps.’) 


To lessen this disadvantage, color map conventions should be used in 
combination with the fill-data instance variable. You do not need to adhere 
strictly to the color map conventions, but following them can save you from 
experiencing problems later if you ever transfer your color software to another 
hardware configuration. This is especially important if your site already has 
more than one type of color system hardware. The color map conventions are 
described in Chapter 3—‘‘Color Maps.” 


Using Default Colors on Color Screens 


You can use colors on the color screen to differentiate windows. For example, 
each window can have its own foreground and background colors. You would 
usually want the backgrounds to be low-intensity pastel colors and the fore- 
grounds to be high-intensity primary colors. 


The window instance variables erase-aluf and char-aluf are used by default 
for drawing operations on all windows. 


erase-aluf is used for :clear-window, :clear-rest-of-line, and similar eras- 
ing operations. The color created by erase-aluf is the “black” of the particular 
window. 


char-aluf is used for all drawing operations, such as :draw-char and :draw- 
line and is therefore the “white” of the particular window. It also draws the 
window borders. 


char-aluf and erase-aluf are gettable, settable, and initable. 


For use as color screens’ erase-aluf or char-aluf, ALUs normally specify 
tv:alu-seta as the alu, -1 as the plane-mask, and an appropriate value of fill- 
data, depending on the color map. 


To use ALUs on both a color screen and a black-and-white screen, you should 
make sure that the following three conditions are met: 


> The low-order bit of char-aluf’s fill-data is a 1. 
> The low-order bit of erase-aluf’s fill-data is a O. 
> The low-order bit of both plane-masks is a 1. 
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: te The effect of the color ALUs on the black-and-white screen is identical to using 
tv:alu-andca and tv:alu-ior, the usual ALU pair. For a description of the varia- | 
ae bles tv:alu-andca, tv:alu-ior, and tv:alu-xor, see the section “Using the 

— Window System” in the document Programming the User Interface. 


ALU Functions and Messages 


The default ALU type is color:general-sc-color-alu. You can create instances 
of this type with make-instance or with the function color:sc-fill-alu. 


color:sc-fill-alu /i//-data plane-mask Function | 
Returns an ALU object with fill-data and plane-mask as specified. Sets ALU | 
code to the value of tv:alu-seta. | 


:compute-color-alu alu-code &rest specs Message 
Transforms color specifications into an ALU object appropriate to that 
screen (taking into account the color map on the screen). This is a message 
of color screens and is the preferred function to use to manufacture ALUs or 
modify the fill-data of existing ALUs. For example: 


rt (send (send window :screen) 
:compute-color-alu 
color:alu-x red grn blu) 


This program segment computes a color ALU for which the fill-data is de- 
rived from the value of the variables red, grn, and blu, based on the color | 
rt maps in use for the color window associated with the variable window. | 
alu-code is normally specified symbolically using the codes listed here. It 
can alternatively be an ALU instance, which is reused. The ALU symbols are 


m1 in the COLOR package and must be prepended with the package name (for 
example, color:alu-x* y) or the compiler assumes that they are undeclared 

xe variables. 

| 

no Note that the first 16 values for alu-code can be represented by a 4-bit 


boolean ALU code (0 to 15). The only reason that the numeric value for the 
ALU-code would be of interest is in the case of a program that performs 


— some logical operation to change the 4-bit boolean value returned for the | 

first 16 ALU-codes shown here. For most color drawing operations, using | 
uaz the symbols rather than the numeric values makes the resulting code much | 
it easier to interpret. 


To perform a pixel operation, use the following symbols, rather than magic 
| numbers. The symbol x refers to the fill-data and the symbol y refers to the 
source pixel. All pixel operations Occur bitwise between the bits of fill-data 
and the bits of the source pixel. 


45 ALU Functions and Messages 


ALU Operation 
Code 


alu-Os 


alu-x*y 
alu--~x*y 


alu-y 
alu-x*~y 
alu-x 


alu-x#y 
alu-x + y 


alu-~x*~y 
alu-x =y 
alu-~x 
alu-~x+y 
alu-~y 
alu-x + ~y 
alu-~x + ~y 


alu-Is 


alu-add 
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Description 


Sets the result to O. 


x and y 
This is the same as tv:alu-and. 


(not x) and y, the usual “erase” ALU 
This is the same as tv:alu-andca. 


Noop 
x and (not y) 


x (result is always fill-data) 
This is the same as tv:alu-seta. 


x exclusive or y 
This is the same as tv:alu-xor. 


x inclusive or y 
This is the same as tv:alu-ior. 


(not x) and (not y) 

Result bit is a 1 if (bitwise) x = y. 
(not x) 

(not x) inclusive or y 

(not y) 

x inclusive or (not y) 

(not x) inclusive or (not y) 


All ones, irrespective of fill-data or the 
original data. 


Supported only in special color micro- 
code: 

x + y (sum of x and y) 
This is the logical extension of xor to a 
color screen. 


. 
= 
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specs can be any of the following types: 


Type 
An integer 
A symbol 


Three flonums 


An ALU instance 


Array Specifications 


color:general-sc-color-alu Flavor 
This flavor defines the following init options and messages. 
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Interpretation 


The actual value to return as fill-data. 


The name of a color, which should have 
been declared previously with the message 
:name-color. 


Red, green, and blue intensity, as a fraction 
from 0.0 to 1.0 inclusive. 


The instance is sent an :rgb message. The 
three values returned are treated as a color 
Spec. 


:array value (for color:general-sc-color-alu) Init Option 
Selects the manner in which pixels are written into color memory. Unless 
you are very sure, value should be :default. 


value can be any of the following: 


:default 
:fill 


:pixel 
:masked-bits 


Array Specifications 


The default. Lets the system choose the best way. 


Specifies fill mode. :fill is device-dependent and 
varies from one hardware type to another. :fill can 
be used to transfer 1-bit arrays to standard color 
screens but not to CAD buffer or broadcast- 
resolution screens. In this operation, the 1s in the 
source array specify which pixels in the destina- 
tion are written with fill-data. 


Specifies pixel mode. 


Similar to :fill but is device-independent and 
therefore can be used on any type of hardware or 
on plain bit arrays. If appropriate, :fill is substi- 
tuted for :masked-bits to take advantage of the 
available hardware. 


The source array (in bitblt operations) or the char- 
acter (in font Operations) functions as a mask. For 
each mask bit that is a 1, the system functions as 


_ serene Sm sia, 


:not-masked-bits 


A, 


though the corresponding point in the destination 
window was drawn using :draw-point and the 
same ALU. All the ALU-codes, the plane-mask, and 
the fill-data are correctly interpreted. 


:masked-bits is, in effect, the means used to im- 
plement font drawing on color screens but was not 
previously available for ordinary bitblt operations. 


Similar to :masked-bits but uses the complement 
of the mask rather than the mask itself. :masked- 
bits or, in some cases, :not-masked-bits should 
be used instead of :fill, unless you know the exact 
characteristics of the fill-mode hardware on the 
screen you are using. 


Specifies packed mode and writes into the red 
color memory. 


Specifies packed mode and writes into the green 
color memory. 


Specifies packed mode and writes into the blue 
color memory. 


Specifies packed mode and writes into the high- 
order byte (pixel overlay) of the color memory. 


The :array field of a color ALU object is a modifier to the function speci- 
fied by the ALU code. :fill, :masked-bits, or :not-masked-bits affect 
only font and bitblt operations. For drawing operations such as :draw-line 
and :draw-rectangle, :fill, :masked-bits, and :not-masked-bits are 
equivalent to an array field of :default. 


It should be noted that, in effect, the changes to the array instance variable 
of extended ALUs apply only to :bitblt and :bitblt-from-sheet. 


:set-array value (of color:general-sc-color-alu) Message 
Sets the manner in which pixels are written into color memory. For a list of 
possible values of value, see the :array init option. 


Fill data can be manipulated in the following ways. 


sarray (of color:general-sc-color-alu) Message 
Returns the manner in which pixels are written into color memoty. For a list 
of possible values, see the :array init option. 


:fill-data 32-bit-number (for color:general-sc-color-alu) Init Option 
Specifies the data that are written into color memory. The default is -1. 
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:Set-fill-data 32-bit-number (of color:general-sc-color-alu) Message 
Specifies the data that are written into color memory. 


:fill-data (of color:general-sc-color-alu) Message 
Returns the data that are written into color memory. 


The plane-mask can be manipulated in the following ways. 


:plane-mask 32-bit-number (for color:general- Init Option 
sc-color-alu) 
Specifies the 32-bit register that enables or disables write on each memory 
plane individually. The default is -1, which means that all memory planes 
are enabled. 


:Set-plane-mask 52-bit-number (of color:general- Message 
sc-color-alu) 
Specifies the 32-bit register that enables or disables write on each memory 
plane individually. 


:plane-mask (of color:general-sc-color-alu) Message 
Returns the 32-bit register that enables or disables write on each memory 
plane individually. 


The pixel mask can be manipulated in the following ways. Note that the pixel 
mask is used by the system to determine which pixels of any given 32-pixel 
block are to be written. The default value should be -1 unless you are very sure 
of what you are doing. 


:pixel-mask 32-bit-number (for color:general- Init Option 
sc-color-alu) 
When the color system is in packed or pixel mode, :pixel-mask controls 
which of 32 sequential pixels are write-enabled. 


:Set-pixel-mask 32-bit-number (of color:general- Message 
sc-color-alu) 
When the color system is in packed or pixel mode, :set-pixel-mask con- 
trols which of 32 sequential pixels are write-enabled. The default is -1, 
which means that all pixels are write-enabled. 


:pixel-mask (of color:general-sc-color-alu) Message 
Returns which of 32 sequential pixels are write-enabled. 


Other ALU-code data can be manipulated in the following ways. Again, note that 
most drawing operations should use an ALU defined by a :compute-color-alu 
message, using one of the symbols rather than the 4-bit boolean value. The 
following init option and messages are useful if you plan to perform some logi- 
cal or numeric operation on the numeric value. 


Array Specifications 


salu alu-code (for color:general-sc-color-alu) Init Option 
Specifies the 4-bit ALU-code as defined by the window system. T he default 
is the value of tv:alu-seta. 


:set-alu alu-code (of color:general-sc-color-alu) Message 
Specifies the 4-bit ALU-code as defined by the window system. 


:alu (of color:general-sc-color-alu) Message 
Returns the standard ALU as defined by the window system. 


Returning ALU Information 


The following messages are used by the color screen to interrogate the ALU 
object. They are not intended for general use of the color system but are in- 
cluded as a reference if you intend to modify the way that ALUs work. 


:1-bit-parameters screen &optional array Message 
Returns ALU-code, fill-data, and plane-mask. It is used by the black-and- 
white screen to interrogate ALUs. ALU-code should be an integer from 0 to 
15. Fill-data should be an integer whose low-order bit is a 1. Plane-mask 
should be an integer whose low-order bit is a 0 or 1. If the plane-mask’s low 
order bit is 0, the operation is a Noop. 


Note: The function (color:combine-data-and-mask alu data mask) 
converts inappropriate fill-data. 


:SC-parameters screen &optional array Message 
m4 Returns (values color-array-type plane-mask pixel-mask fill-data alu). It is 
a} used by all color screens to interrogate ALUs. 


| color-array-type and pixel-mask are internal details. For color-array-lype, 

i the type :default works for all color screens. Other settings are meaningful 

| for particular types of color screens. See the :array init option. For pixel- 
mask, the value -1 should be returned. 


H pixel-mask An integer 

iia plane-mask An integer 

aa fill-data An integer 

| alu An integer, 0 to 15 
Color Debugging Aids 


The following two messages can be sent to the color screen to determine the 
pixel values at screen locations. Use these messages to determine the actual 
Hid color value if you suspect that the color you had expected does not appear on 
| the screen. 
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— :rgb-for-color alu-or-x-and-y Message 
If passed the x and y location of a pixel, returns the RGB values as fixnums 
0 to #01777, and the segment number. If passed an ALU name, returns the 


— | RGB values for that ALU as fixnums, followed by the segment number. 
:flonum-rgb-for-color alu-or-x-and-y Message 
rt If passed the x and y location of a pixel, returns the RGB values as flonums 
. 


between 0.0 and 1.0 inclusive, and the segment number. If passed an ALU 
name, returns the RGB values for that ALU as flonums, followed by the 
segment number. 
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Color Objects 


A color object represents a color simultaneously in an arbitrary number of color 
models. You can use the color editor to set or retrieve the values of color ob- 
jects interactively. All color objects reside in the COLOR package. This chapter 
describes how to send messages to a previously defined color object to change 
or retrieve the values in a color model. 


Creating Color Objects 


There are three ways to make color objects: 


1. Make an instance in the desired color model, with the desired compo- ) 
nent values. For example: 


(defconst color-object (make-instance ‘standard-color 
‘red 0.4 
‘green 0.2 
‘blue 0.2)) 


2. Call the function make-standard-color and pass it the color model and 
the component values. For example: 
(defconst color-object (make-standard-color :ihs ‘(.2 .3 .4))) 


3. Use the color editor to create a color object. See Chapter 10—"Color 
Editor’ for more information on how to use the color editor. 


Color Models 
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A color model contains three components that give a color a unique specifica- 
tion. The subtleties and detailed mathematics of color model theory are beyond 
the scope of this manual. Four color models are provided in standard color 
objects: IHS, hexcone-IHS, YIQ, and RGB. Which color model you use depends 
on your particular application or area of interest. You can also create a new 
color model. (See “Creating a New Color Model” in this chapter.) Briefly de- 
scribed, these are the four color models. 
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The IHS color model mixes colors much the same way an artist mixes paints on 
a palette. The following are the three components of the IHS color model: 


Intensity—Controls the brightness 
of the color. For example, black 
has the lowest intensity, white has 
the highest. The shades of gray 
have intermediate intensities. High 
intensity is toward the right of the 
slider pane and low intensity is 
toward the left. In this model, the 
highest possible intensity is used. 
to represent white and is the 
square root of 3. 


Plate 5.1 JHS color model 


Hue—Controls the frequency of the color. Hue is what most people think 
of as color. For example, red and blue are different hues. 


Saturation—Controls the richness of the color. For example, pure blue has 
a very high saturation. As pure blue becomes pastel and turns into gray, the 
saturation decreases. 


The hexcone-IHS color model closely resembles the IHS color model but uses 
simpler arithmetic to define colors. The main difference between the two is that 
white and red have the same intensity in the hexcone-IHs color model, while 
white is brighter in the IHS color model. The three components have similar 
effects on the color. The hexcone-IHS color model has fewer anomalies than the 
pure IHS color model, and all three components are measured on a scale from 0 


to 1.0. 


The YIQ color model is used in the broadcast-resolution color system. In 1955 
the FCC decreed, through the National Television Standards Committee (NTSC), 
that a color broadcast signal sent out over the airwaves must be compatible with 
4 black-and-white receiver. To conform to this standard, the RGB signal 

output by a color camera is con- 
verted to a YIQ color model and 
NTSC-encoded. In the YIQ color 
model, Y represents luminance, 
and I and Q contain color infor- 
mation. When the YIQ compo- 
nents are received by a color 
system, they are recombined to 
form RGB. In a black-and-white 
system, luminance is used as the 
grayscale and the other two com- 


Plate 5.2 Y/O color model ponents are ignored. 


Abort 
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The RGB color model combines colors much the same way the human eye 
combines the light frequencies of 
the three primary colors. The 
three components of the RGB 
color model represent red, green, 
and blue. The three components 
red, green, and blue also corre- 
spond to the three red, green, and 
blue electron guns in a color mon- 
itor. To mix colors, the three pri- 
maries are added together. For 
example, mixing red and green 
Plate 5.3 RGB color model creates yellow, and mixing equal 
amounts of red, green, and blue 
produce a grayscale color. 


To select a different color model, see the section “Changing the Color Model 
Selection” in Chapter 10—*‘Color Editor.’ To create a new color model, see the 
section “Creating a New Color Model” in this chapter. 


Color model transformations are provided with the color system, so you do not 
have to invent your Own every time you need to use one. The following 
functions transform color model pairs: 


color:rgb->ihs r g b Macro 
Transforms and returns the new values for r, g, and b from an RGB color 
model to the appropriate intensity, hue, and saturation values for an IHS 
color model. 


Example: 


(color:rgb->ihs .3 .4 .5)=> 
0.70710677 

@583833 

0.20135796 


color:rgb-> yigq r g b Macro 
From three RGB component values, computes and returns the correspond- 
ing component values for a YIQ color model. 


color:yiq->rgb y iq Macro 
From the YIQ component values, computes and returns the corresponding 
RGB values in the form of three floating-point numbers. 


color:rgb->hexcone-ihs r g b Macro 
From the RGB values, computes and returns the corresponding component 
values for a hexcone-IHS color model. 
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color:hexcone-ihs-> rgb h-intensity b-hue h-saturation Macro 
From the hexcone-IHS component values, computes and returns the corres- 
ponding component values for an RGB color model. 


color:rgb-> hardware-rgb r g b &optional brange bmin Macro 
Computes and returns the new integer values for 1, g, and b from an RGB 
color model to a hardware RGB color model. brange is an integer represent- 
ing the range within which the new value is to be computed (default 1023). 
bmin is the minimum value, added to the base of the computed value 
(default 0). 


color:hardware-rgb->rgb b-red h-green h-blue Macro 
&optional range min 
Computes and returns the new floating-point values for h-red, h-green, and 
b-blue from a hardware RGB color model to an RGB color model. range is 
an integer representing the range within which the new value is to be com- 
puted (default 1023). min is the minimum value, added to the base of the 
computed value (default 0). 


{ Property Lists 


As shown in the example later in this chapter, the macro define-color-object- 
flavor creates a property list associated with the color model definition. Each 
color model has its own property list. Each color model’s property list is on a 
larger property list associated with the combined flavor. 


For example, to retrieve the property list for the combined flavor: 


(setq info-plist (send color-object :info)) 


Returns a large property list for the combined flavor, including all the property 
lists for the color models and much information used internally by color ob- 
jects. info-plist was set to allow you to retrieve just the property list for a speci- 
fied color model instead of having to retrieve the large amount of the 
information contained in the property list for the combined flavor. 


For example, to retrieve the property list for the IHS color model: 


(setq color-space-plist (get info-plist :ins)) => 


(NIL :-DIMENSIONS (INTENSITY :-HUE :SATURATION) :TO-MESSAGE :TO-IHS 
VALIDATION-VARIABLE COLOR:IHS-VALID :SETMETHOD :SETIHS :COLOR- 
SPACE :IHS ‘COMPONENTS (NIL COLOR:INTENSITY COLOR:HUE COLOR:SA- 
TURATION) :INTENSITY (NIL :SEFMETHOD :SETINTENSITY :ACCESS-METHOD 
NTENSITY :MIN 0.0 :MAX 1.7320508 ‘NAME “INTENSITY” :NICKNAME “Int”) 
‘HUE (NIL :SETMETHOD :SETHUE :ACCESS-METHOD :HUE :MIN 0.0 :MAX 1.0 
(NAME “HUE” :NICKNAME “Hue”) :SATURATION (NIL :SETMETHOD :SET 
SATURATION -ACCESS-METHOD :SATURATION :MIN 0.0 MAX 1.0 :NAME “SATU- 
RATION” :NICKNAME ‘“Sat”)) 
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color-space-plist was set to allow you to retrieve just the property list for a 
specified component of a color model instead of having to retrieve all the infor- 
mation contained in the property list for the color model. Now, you can retrieve 
just the property list for a component of color-space-plist. 


For example, to retrieve the property list for the intensity component: 
(setg intensity-plist (get color-space-plist :intensity)) => 


(NIL :SETMETHOD :SET-INTENSITY :ACCESS METHOD :INTENSITY :MIN 0.0 
“~MAX 
1.7320508 :NAME “INTENSITY” :NICKNAME “‘Int”’) 


intensity-plist was set to allow you to retrieve just a value for the intensity 
component instead of having to find it from the entire intensity property list. 


For example, to retrieve the maximum value for the intensity component: 


(get intensity-plist :max) => 1.7320508 


Messages and Functions for Color Objects 


hardware-rgb window color-object Function 
Computes pixel data from the window and color object and returns the 
values. Applies to a 24-bit system only. 


You can send the following messages to a color object: 


:color-model Message 
Retrieves the object’s three color values for a specified color model. 


Example #1 
(send color-object :rgb) => 0.4 0.2 0.2 


Example #2 
(send color-object :ins) => 0.49 0.0 0.34 
:set-color-model vdluel value2 value3 Message 
Sets the object’s three color values in a specified color model. 
Example #1 
(send color-object :set-rgb 0.2 0.3 0.4) 


Example #2 


(send color-object :set-hexcone-ihs 0.2 0.3 0.4) 


Messages and Functions for Color Objects 


:set-component color-model component value Message 
Sets one component of a color object, in the implied color model (that is, 
setting the value for the component :red implies using the RGB model, 
setting the value for the component :intensity implies the IHS model). 


Example #1 

(send color-object :set-component :red .3) 
Example #2 

(send color-object :set-component :intensity .3) 

:color-component Message 
Retrieves one component of a color object in the implied color model. 
Example #1 
(send color-object :red) => 0.2 
Example #2 


(send color-object :hue) => 0.3 
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color:standard-color is a predefined color object flavor with the following 
color model mixins: rgb-mixin, combined-ihs-mixin, and yiq-mixin. Each 
of these mixins represents a different color model. 


combined-ihs-mixin includes two color models: IHS and hexcone-IHS. As 
previously described in this chapter, hue and saturation are represented identi- 
cally in these color models, but intensity is measured differently. 


The color editor includes four color models: RGB, IHS, hexcone-IHs, Aleve @ OF 


Example—Create a new CMY color model. 


To create a color model called CMY (cyan, magenta, yellow), you must first re- 
late the new color model to an existing color model. This example uses the RGB 
color model. Each color model you create must be related to at least one exist- 
ing color model because the new values are calculated from existing values. For 
example, if the RGB of a color object is set and you send a message asking for 
the IHS values, the IHS values are not known until they are calculated from the 
RGB values. 


(defmacro cmy->rgb (c m y) 
‘(values (- 1.0 ,c) (- 1.0,m)(- 1.0,y))) 


(defmacro rgb->cmy (r g b) 
‘(values (- 1.0 ,r) (- 1.0,g)(- 1.0 ,b))) 
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o Next, define a flavor that can be combined with other color model mixins. In 
this example, the flavor is called cmy-mixin. The only required property is 
es :components, which lists the names of the components of the color model 
— you are creating. The CMY color model components are cyan, magenta, and 
yellow. | 
1: (define-color-object-flavor cmy '(:components (cyan magenta yellow))) | 
me 


If you want to use this newly defined color object with the color editor, you 
— must define the properties and subproperties that the editor will associate with 
= each of the color components. The color editor requires the maximum value, 
minimum value, and name for each color object. When the side labels are on, 
iF you should supply a nickname to specify what is to appear in the slider pane 
= label display. If you do not specify a nickname, the name is used. 


(define-color-object-flavor cmy ‘(:components 
(cyan magenta yellow) 
‘cyan (:min 0.0 :max 1.0 :name “cyan” 
= :nickname ‘“‘cyan’) 
\E -magenta (:min 0.0 :max 1.0 :name 
“magenta” :nickname “mgnta’) 
ou ‘yellow (:min 0.0 :max 1.0 :name 
— “vellow” :nickname “yelow”))) 


: Now the new color flavor exists in a form usable by the color editor. You must 
\E next state to what color model it can be translated. In this example, since CMY 
was previously translated to RGB, define RGB translatable to CMY. 


= (define-translation rgb cmy) 


RGB is now translated to CMY. To use this new mixin to create a new color 


= object flavor, mix in whatever other color models you want. There must be a 
‘= translation path from one color model to another. Next, CMY and the other 

color models are mixed together. Although the details of flavors and mixins are 
ra beyond the scope of this manual, note that basic-color-mixin is always re- 
i~ quired. 


: (defflavor new-color (_ ) 
—— (basic-color-mixin rgb-mixin combined-ihs-mixin 
yig-mixin cmy-mixin)) 
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6 
a Additional Color System Features 


_ In addition to the basic graphics functions already described, the color system 
uF supports additional features, such as key output, line index table, and panning 
and zooming, that might be useful in specialized applications. Some of these 
features, such as key output, require special hardware options. To find out 


\t which color systems support additional features, refer to the appropriate section 
in Chapter 9—“Color Hardware Options.” 
— Using Offscreen Pixels to Create Auxiliary Screens 


If you have a standard color screen, you can use the leftover bits to make an 
t additional screen. This is a “‘real’’ screen in the sense that it has all the hardware 
f capabilities of the main color screen. It can be made visible by using the line- 
index-pan-zoom capability. 


— The immediate use for this is for S-Paint to create menus on an auxiliary screen 
and use line-index-pan-zoom to make them appear instantaneously. 
— Panning and Zooming 


The messages documented here can be sent to several different types of objects, 
it such as standard color screens, color:line-index-pan-zoom objects, and 
windows containing the flavor zoom-window-mixin. Color screens imple- 
ment global pan and zoom using hardware. line-index-pan-zoom provides a 
15 convenient interface to the per-line pan and zoom capabilities of color screens. 
color:zoom-window-mixin provides pan and zoom implemented com- 
pletely in software and can be used to view any window or array. 


it 

met Pan Messages 

=a Two pan registers set the location in color memory at which the video scan 
i starts, independently in x and y. 


You probably want to change pan or zoom operations during vertical retrace to 
i | avoid unsightly unsynchronized changes in the color system’s state during pic- 
ae ture update. To do this, use the optional control argument to specify a control 

register hardware state (returned by the :control, :control-image, or :make- 
| control-image messages). If specified or t, control writes the changes to the 
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hardware image (an array, really) but does not write them to the hardware imme- 
diately. This lets you change the image first and then write the image into the 
actual hardware in one operation. 


The control image follows the same convention as the color map image: that is, 
the system automatically generates a control image that reflects the actual con- 
tents of the control registers, but you can also create your Own control images if 
you wish. Any of these images can then be written to the control register hard- 
ware, and can also be passed to any message that accepts the optional argument 
control. If control is omitted or nil, the changes are written to the control image 
associated with the hardware. 


The window system does not keep track of pan but instead believes that “every- 
thing is visible all of the time » Since this is not true when pan is being used, 
you should reset pan to its original value after panning to restore the color sys- 
tem to its normal state. You can also use FUNCTION Z to do this manually. 


You can send the following messages to the color screen: 


:pan &optional control Message 
Returns the current pan values x and y. 


:set-pan x y &optional control Message 
Sets the pan values x and y for control and returns the previous values. 


:wrap Message 
Returns two values, one for x and one for y. The default value of each is t, 
meaning that the screen wraps in the x or the y axis. If nil, a visible black 
area fills the area outside the visible screen when the screen is panned. 


:set-wrap xX ) Message 
Sets value for x and y to determine whether the opposite margin or a black 
area is displayed when the screen is panned. The default settings are t and t 
for x and y. If t, the display restarts with the first pixel on that axis and so 
wraps around. If nil, a visible black area fills the area to the right and below 
the visible screen. 


i 
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Zoom Messages 


The color system contains two zoom registers that can set pixel replication inde- 
pendently in x and y. The default zoom (pixel replication) of 0 specifies that 
pixels are replicated 0 times (that is, displayed once, not replicated). A zoom of 1 
displays each pixel twice (displayed once, replicated once); a zoom of 2 displays 
each pixel 3 times, and so on up toa maximum replication factor of 255. 


<= ere, ee” 


The window system does not keep track of zoom but instead believes that 
“everything is visible all of the time » Since this is not true when zoom is being 
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(a ; : 
— used, you must reset zoom to 0 after zooming to restore the color system to its 
normal state. You can also use FUNCTION Z to do this manually. 
= FUNCTION 4 Z uses a window containing color:zoom-window-mixin to im- 
o..~ plement a pop-up magnifier window. Look at the code-for the function 
color:pop-up-pan-zoom-window for an example using color:zoom- 
a window-mixin. 
“a You can send the following messages to the color screen: 
ae :zoom &optional control Message 
—— Returns the current zoom values x and y. 
:Set-zoom x y &optional control Message 
i Sets the zoom values x and y for control and returns the previous values. 
7 
Pan and Zoom Messages 
— Global pan and zoom are disabled by per-line pan and zoom. You can send the 
following messages to the color screen: 
ir :pan-and-zoom-p Message 


Returns t if hardware pan and zoom are available. All screens support this 
message. Programs should use this message as the test to see whether pan 
it and zoom are available. If :pan-and-zoom-p returns nil, programs should 
ae: not use any pan and zoom messages. 


_ :Set-pan-and-zoom xpan ypan xzoom yzoom &optional control Message 
iF Sets pan and zoom values simultaneously and returns the previous values. 
:pan-and-zoom &optional control Message 
it Returns the current pan and zoom values: xpan ypan xzoom yzoom. 
Mouse Pan and Zoom Messages 
i ; 
= The following messages use the mouse to affect global pan and zoom. Global 
pan and zoom are disabled by per-line pan and zoom. 
it :keep-mouse-visible-p Message 
Fi Returns t if the screen is automatically panned to keep the mouse visible 
whenever the mouse is on the color screen. 
i 
iv :Set-keep-mouse-visible-p ¢-07r-nil Message 
Sets the pan value to automatically keep the mouse visible whenever it is on 
— the color screen. The default is t. 
i :warp-mouse-to-be-visible Message 
Warps the mouse (as little as possible) to make it visible. If the mouse was 
i | out of the visible part of the screen, it moves to the nearest visible edge. 


—_ 
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:visible-size Message 
Returns two values for x and y that specify the size of the actual display 
raster (determined by the sync program), which might be smaller than the 
screen size. For example, high-resolution color screens can be created up to 
1952 x 1024, but the largest visible size is 1280 x 1024. The “invisible” 


pixels can be made visible by panning. 


:pan-zoom-visible-edges Message 


Returns the left, top, right, and bottom of the visible part of the screen, 
considering pan, zoom, and visible size. 


:pan-from-rectangle /eft top right botiom Message 


&optional zoomed-window 
Sets pan so that the specified rectangle is centered in the visible part of the 
screen. This is useful if you have set zoom so that the area of interest might 
not be in the visible portion of the screen. /eft, top, right, and bottom refer 
to the usual window edge format specifications. The optional zoomed- 
window is the window to which the edges apply. The default is the whole 
of the current screen. 


:pan-and-zoom-from-rectangle-maybe /e/t top right Message 
bottom &optional zoomed-window 
Changes pan and zoom as little as possible to make all of the specified 
rectangle visible. /eft, top, right, and botiom refer to the usual window edge 
format specifications. The optional zoomed-window is the window to 
which the edges apply. The default is the whole of the current screen. 


:pan-and-zoom-from-rectangle left top right Message 
bottom &optional zoomed-window 
Sets pan and zoom to center the rectangle and makes all of the specified 
rectangle visible. /eft, top, right, and bottom refer to the usual window edge 
format specifications. The optional zoomed-window is the window to 
which the edges apply. The default is the whole of the current screen. 


The following interactive methods set pan and zoom: 


FUNCTION Z clears pan and zoom for the current mouse screen if it is color, oth- 
erwise it clears the first color screen. 


:mouse-pan-zoom optional zoomed-window Message 
Enters an interactive loop that pans continuously to keep the mouse cen- 
tered on the screen. To increase the zoom level, click left. To decrease the 
zoom level, click right. To exit the loop, click middle. 


To invoke this message on the color screen, use FUNCTION 2 Z. 
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rma :pan-zoom-from-mouse-rectangle Message 
&optional zoomed-window 
' Sets pan and zoom to zero, does a tv:mouse-specify-rectangle to get a 
a rectangle from a zoomed window, then does a :pan-and-zoom-from- 
rectangle to center on the specified rectangle. 


a To invoke this message on the color screen, use FUNCTION 3 Z. 
oe =] 
:key-set-pan-zoom Message 
—. Enters an interactive loop that uses keys to control pan and zoom. You can 
— chord the keys to do several operations simultaneously. In the following list, 
“Left” refers to the left side of the keyboard and “Right” refers to the right 
= side of the keyboard. For example, ‘‘Left SHIFT key” refers to the SHIFT key 
4 on the left side of the keyboard. 
Left SHIFT key Exit 
fa Left HYPER key Pan left (greater pan x values) 
ae Left SUPER key Pan up (greater pan y values) 
Left META key Pan down 
1 Left CONTROL key Pan right 
—_ Right SHIFT key Zoom x and y out (smaller zoom values) 
Right SYMBOL key Zoom x and y in 
Ia Right CONTROL key Zoom x out (smaller zoom x values) 
—_ Right META key Zoom y out (smaller zoom y values) 
Right SUPER key Zoom y in 
4 Right HYPER key Zoom x in 
To invoke this message on the color screen, use FUNCTION 1 Z. 
_ color:zoom-window-mixin Flavor 
mad Implements the zoom protocols in software, without hardware support. It 
can be mixed with almost any window, including the black-and-white 
= screen. The window acts as a zoomed display window on a part of the rest 
tos of the screen. 
se. The Mouse Pan/Zoom Window program in the color demonstration system 
- uses this mixin. 
= Line Index Table Messages 
{4 


The line index table (LIT) is a hardware array of pointers into the color memory. 
’ Each scanline has two entries in the table: a starting location and an ending loca- 
14 tion for the scanline in color memory. The color screen can have up to 1024 
— possible scanlines (depending on the monitor and the resolution), with a set of 
four entries in the LIT for each scanline (start, end, pan, and zoom). 
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You can send the following messages to the high-resolution color screen: 


:line-index-table Message 


Returns an LIT object (comparable to color map images and control register 
images) which can be manipulated by line index pan and zoom messages. 


LIT setups affect only the video; the actual screen as seen by Lisp is con- 
figured in a standard raster determined by the screen width. 


Note: The screen, the line index table, and the sync program can all have 
different line widths. 


-new-line-index-table-array Message 


Writes the specified 2 x 1024 entry array into the hardware ie 


-make-line-index-table-image &optional displaced-to Message 


Creates and by default returns a new LIT image. If the optional argument 
displaced-to is specified, the LIT image (which the system maintains inter- 
nally as an array) is displaced to the location in memory that corresponds to 
the value of displaced-to. See the manual Reference Guide to Symbolics-Lisp 
for a discussion of displaced arrays. 


-initialize-line-index-table &optional array Message 


Initializes the LIT in the hardware, using default values if no other argu- 
ments are passed with this message. You can also initialize the hardware LIT 
with an array, which can be an LIT image such as one created with :make- 
line-index-table-image. 


-set-line-index-table-image new-image Message 


Specifies the LIT image that is to be used by the system to reflect changes 
made to the LIT hardware. 


-new-line-index-table &optional new-image Message 


Updates the LIT in the hardware. If zew-image is nil, the LIT image used by 
the system to reflect changes made to the hardware is used to update the 
hardware LIT. Otherwise, the image passed as the value of new-image is 
used. 


:line-index-table Message 


Returns the current contents of the hardware LIT. 


:line-index-table-image Message 
Returns the LIT image currently used to reflect changes made to the hard- 
ware LIT. 
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= Line Index Pan and Zoom Messages 
—— Screens that have a line index table can also set pan and zoom for individual 
= lines. Global pan and zoom are disabled by line index pan and zoom. 


As described in the pan and zoom mode section, it is possible to set pan and 
zoom values for the entire screen separately in x and y. It is also possible to set 


——_ pan and zoom in the x direction for every scanline. When this mode (:x-zoom- 
from-lit or :x-pan-from-lit) is enabled, the screen-wide pan and zoom for x is 
= disabled (lit stands for line index table). 
14 


line-index-pan-zoom provides a convenient means to pan and zoom the 
standard color system by individual lines. The basic capability provided is to use 
1 any contiguous group of lines into a pan/zoom region. You can have as many of 
» these as you want. See the Spheres demo in the color-demo system for an exam- 
ple of the use of line-index-pan-zoom objects. 


md :line-index-pan-zoom Message 
If t, panning and zooming are controlled per-line rather than globally. 


[4 :set-line-index-pan-zoom f-or-nil Message 
re Enables or disables line index panning and zooming. If disabled, the screen 
is restored to its default state; that is, all line index tables and pan/zoom 
parameters are returned to their original state. 


| 
I! wv 
color:line-index-pan-zoom Flavor | 
: line-index-pan-zoom objects are independent entities that accept the 
—. usual pan/zoom messages, including the complex ones such as :mouse- 
pan-zoom. Each line-index-pan-zoom has two associated screens, 
ae which are normally the same standard color screen. 
ae - 
| fees | 
Init Options for line-index-pan-zoom 
| :dest-screen The screen where zooming and panning take place. This 
a must be a standard color screen. The default is the 
current standard color screen, if there is one. 
| :SOurce-screen The screen where the zoomed and panned bits come 
from. This is usually the same as dest-screen, the 
2 default, but it can also be an auxiliary screen made from 


= unused screen memory of dest-screen. See color- 
bitmap-on-real-screen for more about this. 


It :first-line The first line of the destination screen that is used for 
—_ display. Defaults to 0. 
4 
(= 
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slast-line The last line of the destination screen that is used. De- 
faults to the first line plus the height of the source screen. 


:border-lines The number of blank lines with which to border the 
zoom area. Default is 2. Due to hardware glitches, 0 and 1 
are not recommended. 


You can send the following messages to the color screen: 


:x-zoom-from-lit Message 
Returns t if :x-zoom-from-lit is enabled; otherwise, returns nil. 


:Set-x-zoom-from-lit boolean Message 
If boolean is t, :x-zoom-from-lit is enabled and the global zoom mode in 
the x direction is disabled. If boolean is nil, :x-zoom-from-lit is turned 
off. 


:x-pan-from-lit Message 
Returns t if :x-pan-from-lit is enabled; otherwise, returns nil. 
:set-x-pan-from-lit boolean Message 


If boolean is t, :x-pan-from-lit is enabled. If boolean is nil, this mode is 
turned off. 


:line-pan-zoom-for-line /ine-number Message 
Returns two values, the pan-zoom counts for /ine-number. 


:set-line-pan-zoom-for-line new-pan new-zoom line-number Message 
Sets the pan and zoom counts for /ine-number. 


:line-pan-zoom-image-from-line /ine-number &optional table Message 
Returns the line pan and zoom for any pan-zoom image. The default is the 
default pan and zoom image. 


:Set-line-pan-zoom-image-from-line new-pan new-zoom Message 
line-number &optional table 
Sets line pan and zoom for any pan-zoom image. The default is the default 
pan-zoom image. 


:line-index-pan-zoom Message 
Returns t if the destination screen is in line-index-pan-zoom mode. 


:Set-line-index-pan-zoom f-or-nil Message 
Sets the line-index-pan-zoom status of the associated screen, and if enabling 
:line-index-pan-zoom, starts panning and zooming. 


:pan, :set-pan, :zoom, :set-zoom, etc. Message 
All pan/zoom protocol messages are accepted. 
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Hardware Cursor Messages 


A high-resolution color system with a standard color paddle board implements a 
64 x 64 pixel hardware cursor. The cursor is defined as a 2D array. Each element 
of the array selects a color map to use for that bit of the cursor. Valid color map 
numbers are from 0 to 3. 


— 


You can send the following messages to the color screen: 


:cursor-visible? &optional control Message 
Returns t if the cursor is enabled, nil if it is not. 


:Set-cursor-visible? boolean &optional control Message 
Turns off the cursor if boolean is nil; if boolean is t, enables the cursor. 
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:Set-cursor-position x y Soptional control Message 
Sets the current x and y location of the cursor array. 


i 


:cCursor-image Soptional control Message 
Returns an array that is an image of the cursor. The image can then be used 
to create a new cursor that is activated with the :new-cursor message. 


im 


:new-cursor new-cursor &optional control Message 
new-cursor should be a 2D array that defines the new cursor. new-cursor is 
displayed after the next vertical retrace. 


Ey 


Control Register Messages 


The state of the color system is described and controlled in the control registers 
that are on the color controller board. The control register image follows the 
same convention as the color map image: that is, the system automatically gen- 


ey 


aa 

erates a control image that reflects the actual contents of the control registers, 
but you can also create your own control images if you wish. Any of these 

aa images can then be written to the control register hardware. In addition, wher- 

= ever a message (such as those listed in “Hardware Cursor Messages” or ‘“‘Keying 


Messages’’) shows an optional argument of control or control-image, a control 
image can be passed to the message to specify the control image to be used for 


— | that operation. Use the following messages to set registers and bits directly. 
:control Message 
= Returns an array that contains the current state of the control registers. 
vt 
:control-image Message 
Returns an array that contains the contents of the control register image 
array. 
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-make-control-image Message 
Creates a new control register image array. The initial contents of the new 


image are unspecified. 


:new-control new | Message 
Sets the control registers to the contents of the symbol new. 
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The key capability provides a way to mix video using auxiliary video informa- 
tion produced on a fourth channel. Keying allows you to mix images from 
frame buffers or video sources to form a composite image. For example, this 
technique is often seen on commercial television during a news broadcast when 
an image of a broadcaster is combined with a background image. Keying is also 
used to effect dissolves between images or to soft-matte several images. 
The chroma board has four outputs: red, green, blue, and key. Key is just like 
the other three—in fact, you can hook the key output to a monitor in place of 
one of its other inputs. Video switching gear uses key signals (generated by 
many different means) to control common video effects such as wipes and 
dissolves. 
With the chroma board, you can generate a key signal based either on what 
colors are on the screen (chroma key) or on certain areas of the screen (alpha 
key). 
Chroma key is a generalized “blue screen” technique. You use color system 
messages to mark a group of colors, and wherever any of the marked colors 
occur on the screen, the chroma board generates a specified level on its key 
output. This technique is used to superimpose figures against backgrounds, for 
example, making the T'V weatherman appear over the satellite photograph. This 
could be accomplished by marking the blank wall behind the weatherman, 
setting the value for that color to 0, and then combining the image of the weath- 
erman and the satellite map on one screen. 
Alpha key lets you paint a matte of an arbitrary shape and generate key signals 
depending on the matte density at each point on the screen. This technique can 
be used to put one image inside a cutout of an arbitrary shape. 
For example, the weather report could continue by showing film clips of the 
raging flood waters framed by a background chart of local temperatures Of €X- 
pected rainfall. 
Broadcast industry standards measure the key value of a key signal in IRE units, 
where zero IRE units correspond to “no keying” (only the first image is visible) 
and 100 IRE units correspond to “full on” (only the second image is visible). 
Symbolics color system controllers specify the IRE units using an integer from 0 
to 255, where a value of 255 corresponds to 100 IRE units, or “full on.” 
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Chroma key mode lets you specify a key value per color. The chroma key value 
can be an integer from 0-255. At 0, the color disappears from the composite 
image; at 255, it overrides any other colors at the same location. 


Alpha key mode lets you specify a key value per pixel, independent of its color 
value. The alpha key value can be an integer from 0-255, with the same 
correspondence as for chroma keying. Data from the fourth memory plane 
indexes into the alpha key value array, and the data contained there becomes the 
alpha key level. If the color map contains chroma key values, they are still 
effective and override the alpha key level. 


Chroma key color selection is done using an auxiliary chroma key select bit for 
each color map entry slot or for each color. When the video pulse finds ail 
three chroma key select bits for red, green, and blue on, the color is selected 
and chroma keying occurs. Otherwise the key signal outputs 0 IRE units, 
meaning no chroma keying. 


Chroma matte is used in conjunction with the chroma key to generate positive 
or negative hard-edged mattes. A hard-edged matte is generated when the 
chroma matte video setup level is adjusted to a level lower than a video signal’s 
normal black level, called “blacker-than-black.’ The video setup level is adjusted 
via a trimpot on the broadcast-resolution or chroma key paddle board, and is 
therefore supported only on systems equipped with one of these paddle boards. 


For example, you can turn on chroma matte exactly where chroma keying is 
enabled, so the keyed areas of the video become total black “holes.” This way, 
the keyed areas are readily visible, and a video switcher does not need to 
‘“‘remove”’ the keyed areas before inserting other video. 


ee Example—Blank out certain shades of green using chroma matte. 


1. Use the NTSC Color Bars test pattern from the color demonstration sys- 
tem to display the NTSC color bar chart. 


2. Reset the chroma matte bits. 


=r (send color-screen :multiple-set-chroma-key-blanking-select nil | 
0 255 '(:red :green :blue) ) | 
ss | 
i 3. Blank the high green shades. 
a (send color-screen :multiple-set-chroma-key-blanking-select t 
‘= 250 255 ’(:green ) ) 
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4. Because the NTSC color bar chart assigns a very low amount of red and 
blue to the green color bar, it is necessary to assign those colors as well. 


(send color-screen -multiple-set-chroma-key-blanking-select t : 
0 3 ‘(:red :blue ) ) 


5. Finally, when you are through, reset the chroma matte bits. 


(send color-screen -multiple-set-chroma-key-blanking-select nil 


250 255 '(:green ) ) 
(send color-screen -multiple-set-chroma-key-blanking-select nil 


03 ‘(:red :blue ) ) 


Keying Messages 
Keying is not supported on the CAD buffer or on the digitizing frame grabber. It 
is used mostly in a studio production environment. 


All color controllers accept the following messages: 


:chroma-key-modes Message 
Returns a list of modes describing the keying modes available, or nil if the 


controller does not have any keying capabilities. 


Programs should use this message as the test to see if keying is available. If 
the result is nil, programs should not use any of the other keying messages. 
The keying messages should be sent only to a color controller. 


The modes returned by this message might be some combination of the 


following: 

:none The key signal value is always 0 IRE units, meaning no 
keying. 

:chroma-key The key signal value is activated per color. 

:alpha-key The key signal value is activated per pixel. 


In all of the following messages, the control-image argument should be one of 
the following: 


A control image, returned by the :control, :control-image, or :make- 
control-image messages 


t, indicating the default control image 


nil, indicating the actual control hardware 


:chroma-key-mode &optional control-image Message 
Returns two values: the current keying mode and the current chroma key 
value. 
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:set-chroma-key-mode optional new-mode Message 
new-key-value control-image 
Returns the previous value of :control-key-mode. new-mode is one of the 
valid modes for the controller, or nil to indicate no change. new-key-value 
is an integer from 0 to 255, indicating the chroma key value, or nil to 
indicate no change. 


:Soft-key-value Soptional index control-image Message 
Returns the alpha key value for that index entry (slot number). 7ndex is an 
integer from O to 255, and is the index entry (slot number) for alpha keying. 


:Set-soft-key-value new-value index Message 
&optional control-image 
Changes the alpha key value for index to be new-value. 


:chroma-key-select index color Message 
&optional segment-number map 
Returns t or nil, the chroma key select for a color map entry (t means 
chroma key on; nil means chroma key off). 


index OH1O7259 

color :red, :green, or :blue 

segment-number An integer in the valid range. The default is as 
returned by the message :default-map-segment- 
number. 

map The color map to use. If map is omitted, the color 


map image associated with the hardware is used. 


:Set-chroma-key-select new-value index color Message 
segment-number &optional map 
Changes the select bit for a color map entry. new-value is t or nil. 


:multiple-set-chroma-key-select Message 
new-value first-index last-index colors 
&optional segment-numbers map 
Does multiple sets, similar to the previous message. Changes a range of 
color map slots from first-index through last-index. colors can be either a 
single color (one of the symbols :red, :green, or :blue) or a list of colors. 
segment-numbers can be either a single map segment number or a list of 
map segment numbers. map is the color map to use. The default is the 
color map image associated with the hardware. 


Keying Messages 


Chroma Matte Messages 


The following three messages are similar to the three chroma key select mes- 
sages, except they operate on the chroma matte bits instead_of the chroma key 
select bits. | 


:chroma-key-blanking-select index color Message 
segment-number &optional map 
Returns t or nil, the chroma matte select for an entry ina color map. 


a index 0 to 255 
3 color :red, :green, or :blue 
a segment-number An integer in the valid range. The default is as 
returned by the :default-map-segment-number. 
& map The color map to use. If map is omitted, the color 
s map image associated with the hardware is used. 
- :set-chroma-key-blanking-select new-value index Message 
ie color segment-number &optional map 


Changes the select bit for a color map entry. new-value is t or nil. 


— :multiple-set-chroma-key-blanking-select value Message 
— first-index last-index colors &optional 

te segment-numbers map 

Does multiple sets, similar to the previous message. Changes a range of 
entries from first-index through Jast-index. colors can be either a single 
color (:red, :green, or :blue) or a list of colors. segment-numbers can be 
either a single map segment number or a list of map numbers. 
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4 | | | The digitizing frame grabber option allows you to capture video images from a 
— camera or other video input source such as a VTR and store these images digi- 
tally in the Lisp Machine. Once the image is stored, you can then manipulate it 
using the tools available on the color system. 


} 

| Most framegrab operations can be accomplished using the system's default 

| parameters. However, you can change any of these parameters from the Frame 

; | Grabber Parameters menu or by using software described in “Custom framegrab 
q _ | operations” later in this section. If your use of the frame grabber consists pri- 


4 | marily of copying direct color images with default color maps and no special 
— processing, you can probably ignore the custom framegrab operations. If you 
| have special hardware or special processing needs, you should read this entire 
i section. 
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Before grabbing a frame, you need two things: 


» A frame grabber screen to which you send messages to control grabbing. 


>» A window on a color screen for displaying the framegrabbed image. 


If you are transferring the grabbed image to an array or a group of arrays, as 
described later, the color window can be omitted. 


You create a frame grabber screen using the function color:make-framegrab- 
screen. 


color:make-framegrab-screen &rest keywords Function 
Creates a screen with standard broadcast-resolution dimensions. The screen 
is automatically exposed and activated. Since framegrabbing normally re- 
quires specific hardware, you should not need any keywords; if you find it 
necessary to customize your screen, you can pass this function any of the 
keywords listed under color:make-color-screen in Chapter 2—‘Color 
Window System.” 


Example—Make an NTSC-format frame grabber screen. 
Use the following arguments to color:make-framegrab-screen: 
(defvar *ntsc-frgb-scrn* 
(color:make-framegrab-screen)) 
Example—Make a PAL-format (European video format) frame grabber 
screen. 
Use the following arguments to color:make-framegrab-screen: 
(defvar * pal-frgb-scrn* 
(color:make-framegrab-screen :sync-program :pal)) 
Frame grabber screens also accept the full complement of color-map messages, 
which are accepted by all color screens. 
Note: If you get an error when you try to create or expose a frame grabber 


screen, refer to Appendix A—‘“‘In Case of Trouble.” 


Simple framegrab operations use the default values with which the system is 
initialized automatically. To grab a frame the easy way, select the [Grab Frame] 
option of the color demonstration system. This menu-driven framegrab method 
uses the system’s defaults. 


From within a program, a simple interactive way to grab a frame is to use the 
function color:grab-frame. 


Frame Grabber Messages 


color:grab-frame window Function 
Sets up a frame grabber screen, grabs a frame, transfers the frame to win- 
dow, and displays a menu of options. A simple view of its effect is as 
follows: 


1. Finds or creates a frame grabber screen. 


2. Finds or creates a set of default parameters, based on the destination 
screen (the superior of window). 


. Sends the message :transfer-frame to the frame grabber screen; this 
message grabs the frame and transfers the result to window. 


The menu options are: 


[Set Grab Parameters] Calls the function choose-framegrab- 
parameters, described later in this 
section. 


[Save Viewing Window] Saves the picture currently on the 
viewing window. 

[Save Frame Grabber Buffer] Saves the picture currently in the frame 
grabber. 


[Grab Once Again] Repeats the grab using current 
parameters. 


[Loop Indefinitely] Loops using current parameters until 
you type any key. 


[Double Buffered Loop] Sets up windows for a double-buffered 
input loop. 


[Mouse Controlled Wash] Repeatedly transfers the image from a 
small rectangle selected by the mouse. 


[Exit] Returns to program control. 


From this menu, you can continue grabbing or change the default parameters. 
Use this function as a means of easily and interactively experimenting with the 
effects that different parameters have on the framegrab operation. 


Using the system defaults should suffice for most common circumstances, such 
as grabbing a video image for retouching with some of the functions available to 
the color system. For example, once you have grabbed a frame, you can save it 
by using the [Load or Save Images] option of the color demonstration program 
or by using the IMAGES functions directly. See Chapter 11—“IMAN System.” 
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Grabbing an Image 


To framegrab an image without using the Frame Grabber Parameters menu, send 
the message :transfer-frame to the frame grabber screen. The only parameter 
that you must pass to :transfer-frame is the destination window to which you 
want the captured information to be displayed. You can specify many options 
with the :transfer-frame message; however, you do not need to specify values 
for anything except the destination window, unless you want to specify your 
custom parameters for transferring a frame. The keywords that control these 
custom parameters are described later. 


Example—Transfer a frame. 


This example assumes *frgb-scrn* as created earlier in this section and a win- 
dow of your color screen called *frgb-win*: 


(send *frgb-scrn* :transfer-frame *frgb-win”) 


The image being displayed by the video source is now displayed on the color 
window *frgb-win*. Remember, *frgb-win* is a window of the color 
screen, not of the frame grabber screen; you cannot create a window on the 
frame grabber screen. 


Custom framegrab operations exert more specific control over the frame 


grabber parameters than grab-frame permits. If you have needs that are not 
met by the system defaults, you can explicitly specify the parameters that are 
important to you as keywords to the message that captures the image. 


Many parameters control various aspects of a framegrab, such as the color maps 
to use, the location in the frame buffer to which the grabbed image is stored, 
and the factor by which the grabbed image is to be replicated (zoomed). To 
control all these aspects, the software uses a list of parameters collectively 
referred to as a type. The list of these parameters can be passed to the software 
through the :type keyword of the :transfer-frame message, explained later. 


To make it easier to grab frames, the system is set up with three types 
predefined by the system software: :full-color, :false-color, and :b&w. For 
most framegrab operations, one of these system default types should give you 
usable results. You do not need to specify any parameters that you do not wish 
to change. 


However, to give you complete control over the framegrab parameters, the 
message :transfer-frame offers numerous keywords (listed and described later 
in this section) that you can use to change all the framegrab parameters. To 
simplify later use of your framegrab program, you can define new types of your 
own. The advantage to defining your own type is that a custom type gives you a 
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single, mnemonically named keyword that you can pass to :transfer-frame; 
that single keyword specifies as many of the framegrab parameters that concern 
you. The functions for creating your own types are described later in this sec- 
tion. 


Specifying Video Source and Screen Type 


There are four common combinations of video source and screen type. Each of 
these combinations has a recommended :type parameter with which it is asso- 
ciated. 


> Full color video viewed on a direct color (24-bit) screen. Use 
:type :full-color. This is the most common configuration, using either 
an RGB camera or a standard color video source with a decoder. 


>» Monochrome video viewed on a direct color (24-bit) screen. Use 
:type :b&w. On 24-bit direct color screens, the single frame is copied 
three times, once into all three color planes. 


» Monochrome video viewed on a pseudo-color (8-bit) screen. Again, use 
stype :b&w. On 8-bit pseudo-color screens, you need a special grayscale 
color map on the viewing screen. 


» Full color video viewed on a pseudo-color (8-bit) screen. Use 
:type :false-color. Note that with this combination of equipment, you 
cannot get full color fidelity. This mode uses special color maps on both 
the frame grabber and the viewing screen. 


Specifying Custom Framegrab Parameters 


You can specify custom parameters by using the numerous keyword arguments 
of the :transfer-frame message. Some of these arguments are interdependent 
and are noted as such; others are independent. Again, these keywords can be 
ignored unless your application specifically needs to change one or more of the 
parameters that these keywords affect. Also, if you have defined your own 
:type keyword, all you have to specify is that keyword and all the other values 
are set as you have specified. 


-transfer-frame window &rest keywords Message 
Copies the image from the external video source to the destination speci- 
fied by the parameter window. Although the simplest value of window, as 
demonstrated in the preceding example, is a window of the frame grabber 
screen, it can optionally be an array, a list of windows, or a list of arrays. 
The typical reason for passing a list of arrays as the value of window is to 
copy specific color bitplanes from the image being grabbed into specific 
arrays used to represent the individual color bitplanes. The typical reason 
for passing a list of windows is for double-buffered input, such as might be 
used for zooming. 
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Example—Transfer a grabbed image to a set of arrays. 


(setq 
red-array (make-array ‘(640 484) :element-type ’(unsigned-byte 8)) 
green-array (make-array ‘(640 484) :element-type ‘(unsigned-byte 8)) 
blue-array (make-array ‘(640 484) :element-type '(unsigned-byte 8))) 


(send *frgb-scrn* 
‘transfer-frame ‘(,red-array ,green-array ,blue-array)) 


Note two things in the preceding code: first, the backquote (not quote) and 
commas in the list of arrays; second, the Common Lisp specification for making 
arrays of type art-8b. This array type is the fastest array to use for this operation. 
Note also that by default, :colors and :to-colors (defined later) both indicate 
that all three bitplanes are written in RGB order. The order of the arrays passed 
to :transfer-frame must reflect the current order specified by the keyword 
:to-colors. When this form is evaluated, the three arrays have the bit values for 
their respective color component. 


Example—Perform a double-buffered image loop, zooming in to 
twice the image’s original size. 


(send *frgb-scrn* :transfer-frame (list window1 window2) 
‘loop t :Zoom 2) 


The input loop writes a framegrabbed image approximately every two seconds, 
alternating between window1 and window2 and doubling the image size. 


The following is the list of all keywords you can pass to :transfer-frame: 


:type This is the type such as might be returned 
or specified by the function color:default- 
grab-parameters, defined later. The de- 
fault value for :type is :full-color. The 
:type parameter is used to set an explicit 
value for each of the other keyword op- 
tions; creating types as defined later can 
greatly simplify your use of the frame grab- 
ber, letting you choose from framegrab 
setup types rather than forcing you to set 
values for all the keywords of interest to 
your framegrab operation every time you 
call :transfer-frame. This is important 
since the setups for framegrabbing differ de- 
pending on the type of screen and the type 
of camera in use. 


Frame Grabber Messages 


:default-parameters /ist Fine-tunes the :type keyword at runtime. 
This option can be used instead of the 
:type parameter to supply an explicit list of 
keyword /argument pairs to override the list 
specified by :type. 


:set-color-maps f-or-nil Default is nil. If t, the frame grabber and 
destination screen color maps are initialized 
as specified by the :grab-color-map, 
:view-color-map, :grab-gamma, and 
:view-gamma options. 


:loop Loops :transfer-frame until you press the 
END key. Twenty-four-bit color frames are 
transferred at about two per second. The 
default is nil. 


The following example performs a continu- 
ous double-buffered transfer loop, alterna- 
tively displaying the grabbed image on 
windowl1 and window2. 


(send frame-grabber :transfer-frame (list window1 window2) 
‘loop t :zoom 1) 


:colors Specifies which color planes of the source 
are transferred to the destination window or 
array. Can be :red, :green, :blue, or a list. 
The default is ’(:red :green :blue), which 
is appropriate if you are doing a normal 
color grab. 


:to-colors Specifies which planes of the destination 
are written, from the corresponding planes 
specified by :colors. The default is 
’(:red :green :blue). Combined with 
:colors, this keyword transfers from any 
color plane on the frame grabber to any 
color plane of a color window. 


To transfer a black-and-white frame to a 24- 
bit color screen, assuming the green chan- 
nel of the frame grabber is being used as a 
monochromatic input, the following exam- 
ple writes the pixel data from the green 
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channel into all three output planes of the 
24-bit frame buffer: 


(send frame-grabber :transfer-frame window 
‘colors ‘(:green :green :green) 
‘to-colors ‘(:red :green :blue)) 


To transfer a black-and-white frame to an 8- 
bit color screen, assuming the green chan- 
nel of the frame grabber is being used as a 
monochromatic input, the following exam- 
ple writes the pixel data from the green in- 
put channel to the red plane of the 8-bit 
frame buffer: 


(send frame-grabber :transfer-frame window 
colors :green 
‘to-colors :red) 


:grab Grabs a new frame before transferring to the 
destination window. The following values 
are possible: 


:grab t 

Causes an immediate framegrab, then trans- 
fers the grabbed image to the frame buffer. 
This is the default. 

:grab nil 

Transfers the frame already in the frame 
grabber buffer, without grabbing a new 
frame. Used with the message :grab- 
frame, described in the section ‘Separate 
Grab and Transfer.’ 


:grab :external-trigger 

Enters Lisp into a wait loop until the exter- 
nal trigger causes a frame to be grabbed. 
Several messages used to support the exter- 
nal trigger are described in the section “Ex- 
ternal Trigger Support.’ 


The ability to control grabbing and transfer- 
ring separately can be useful if you need to 
perform some function between the time a 
frame is grabbed and the time it is trans- 
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i :grab-gamma 


:view-gamma 


:grab-color-map 
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ferred to the frame buffer; an example is 
provided with the message :grab-frame, 
described in the section “Separate Grab and 
Transfer.’ ve 


Specifies the color ALU used to specify 
color images being grabbed. The default is 
tv:alu-seta. When multiple planes are 
being transferred, :first-alu can specify a 
different ALU to be used on the first plane. 


Specifies the ALU to be used on the first 
plane of the transfer. This interaction of 
:first-alu and :alu is used to implement 
pseudo-color framegrabs, where red is 
transferred with tv:alu-seta and green and 
blue are then transferred using tv:alu-ior. 


Specifies the zoom factor for the screen (as- 
sociated with the destination windows) as a 
number between O and 255. Screen zoom is 
set to :zoom, and pan is set to place the 
upper-left corner of the current window at 
the upper-left corner of the screen. Specify- 
ing :zoom with at least two windows in the 
output list results in smooth double buf- 
fering, because it allows you to view one 
window at a time. The default is nil. 


Specifies the gamma correction factor for 
the video camera to be applied to the image 
being grabbed. The factor is expressed as an 
exponent used to plot the gamma correc- 
tion curve. 


Specifies the gamma correction factor for 
the monitor to be applied to the frame- 
grabbed image being displayed. The factor 
is expressed as an exponent used to plot the 
gamma correction curve. 


Specifies the color map used for the image 
being grabbed. Can be any color map image 
you have created; the default is the color 
map image that reflects the current hard- 
ware color map values. 
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:view-color-map Specifies the color map to be used when 
displaying the image being grabbed. Can be 
any color map image you have created; the 
default is the color map image that reflects 


the current hardware color map values. 


:shold-frame Allows you to specify a hold-frame key. If 
the hold-frame key is pressed, the grab loop 
pauses until you press another character. 


The default is #/SPACE. 

:dx and :dy Specifies the x and y starting point in the 
frame buffer of the grabbed image. The de- 
fault is O. 

:wdx and :wdy Specifies the x and y starting point of the 


transferred image in the destination win- 
dow. The default is 0. 


Specifies the x and y size of the transferred 
image. The default is determined by com- 
paring the frame grabber and the destina- 
tion window and using the smaller of the 
two values. 


:width and :height 


The preceding three pairs of keywords let you specify exactly which portion of 
the grabbed image is to be transferred, the location in the destination to which 
it is transferred, and the width and height, in pixels, of the transferred image. 
Use these three pairs to copy sections of the framegrabbed image into specific 
locations on the destination window. 


Separate Grab and Transfer 


If your program requires more detailed control of the framegrab operation, you 
can divide it into two parts: 


>» Capturing the video image in the frame grabber’s internal buffer (the 
grab). 
>» ‘Transferring this image to the designated window in the frame buffer, or 


to an array or list of arrays as specified in the window argument to 
:transfer-frame (the transfer). 


The :grab keyword of the :transfer-frame message is one of the means for 
controlling this two-part operation. Two additional messages are also available 
and might be used in conjunction with the :grab keyword: 
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:grab-frame &optional (wait t) Message 
Triggers the frame grabber hardware to capture an image from the external 
video source. If wait is t, the frame grabber waits for a previously started 
grab (if any) to finish, then it grabs the image coming in from the external 
video source. The image is not transferred to the frame buffer but must be 
explicitly transferred with a :transfer-frame message. Note also that you 
need to specify :grab nil in the subsequent :transfer-frame message. 


Example—Modify the framegrab parameters after grabbing an image 
but before transferring it. 


Suppose you are interested only in transferring part of a grabbed image. You 
might want to view the grabbed image on the external video’s monitor to deter- 
mine what part you want to transfer. Then you can change the :dx, :dy, :wdx, 
:wdy, :width, and :height keywords accordingly. The following example calls 
the choose-framegrab-parameters function, which displays a menu of the 
:transfer-frame keywords, after grabbing the image but before transferring it 
to the destination window: 


(send *frgb-scrn* :grab-frame) 

(setf (default-grab-parameters :your-type-here) 
(choose-framegrab-parameters)) 

(send *frgb-scrn* :transfer-frame :type :your-type-here :grab nil) 


If you do not specify :grab nil, you will lose the framegrabbed image in the 
first Lisp form. 


Note also that the message :grab-frame, described here, is completely distinct 
from the function grab-frame, described previously. 


:wait-for-grab-done Message 
Waits for a previously started grab (if any) to finish before the program 
continues beyond this point. No grabbing or transferring is done. 


Creating Your Own Values for the :type Keyword 


The facility to create your own values for the :type keyword can greatly sim- 
plify your use of the frame grabber. The benefit is that complex setups can be 
stored in a new type and accessed with the new type name. Once you define 
the type, you do not need to remember to specify each keyword every time you 
grab a frame. Two functions let you create new types and edit existing types: 
default-grab-parameters and choose-framegrab-parameters. 


The function default-grab-parameters lets you see or manipulate the values 
for all the parameters of any type that has been defined by you or by the system: 
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color:default-grab-parameters type Function 
Returns or sets the default parameters for the :transfer-frame message 
associated with the setup passed as type. The system is initialized with three 
Wik default setups, corresponding to the three most common. combinations of 


aa frame grabber with screens. When you call make-framegrab-screen, it 
ian picks the setup that is most appropriate for the type of hardware in the 
wi system. 

The following default setup types are available from the system and can be 
_ passed as the value of type: 
-——— 
a :full-color for a full RGB grab to a direct color screen. 
ee :b&w for a grayscale (black-and-white) grab to an 8-bit screen. 
- :false-color for a pseudo-color grab to an 8-bit screen. 
ae In addition, any setup type that you define, as described later, can be passed 
Te | to default-grab-parameters. 

You can also use this function to change an existing setup type or create a 
ae new one; any new Ones you create can be passed to :transfer-frame as the 
— value of the :type keyword. Use a Lisp form in the following format: 


(setf (default-grab-parameters type) new-values) 


ers type in this example represents the new type name under which your new 
setup is to be accessed, and new-values is some Lisp form that evaluates to 

ut the new settings you want to use. Typically, the form is a list of the key- 

= words to :transfer-frame, with their new values, that you need to change 
in order to achieve your customized framegrab. You need only to change 

7 the keywords that concern your operation; the new type retains the default 

na settings for all keywords unless you explicitly specify them. 


it ee Example—Create a new setup type in which only the red and green 
- planes are transferred with continuous grabbing. 


eis (setf (color:default-grab-parameters :my-way) 
‘(:colors '(:red green) loop t)) 


After evaluating this form, the setup :my-way is available for use as a value of 
. the :type keyword of the :transfer-frame message; sending the message 


(send *frgb-scrn”* :transfer-frame :type :my-way) 


rs is functionally identical to sending the message | 


(send *frgb-scrn* :transfer-frame :colors ’(:red :green) :loop t) 
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This is a very simple example, but it demonstrates the basic technique for creat- 
ing new types with the function default-grab-parameters. 

You can also create new types interactively from a menu. T his gives the user of 
your program the option of setting up a new type at runtime. It is accomplished 
by calling the function choose-framegrab-parameters. 


color:choose-framegrab-parameters Function 
&optional defined-type 
Pops up a menu of all the keywords (except :type) that can be passed to 
-transfer-frame. You can interactively specify the parameters you want 
and when you exit the menu, choose-framegrab-parameters returns an 
object that can be passed to :transfer-frame as the :type keyword. 


If you give it a value for defined-type that corresponds to some previously 
defined type, choose-framegrab-parameters lets you edit the definition 
of that type and stores out the new values under that name. 


Example—Make a new setup called :new-type with values chosen 
from the choose-framegrab-parameters menu. 


(setf (color:default-grab-parameters "new-type) 
(color:choose-frameg rab-parameters)) 


The call to choose-framegrab-parameters pops up a menu with all the 
parameters that can be modified, and with their current values displayed; 
choose only parameters you want to change. When you have made all the selec- 
tions you need and exited from the menu, choose-framegrab-parameters 
returns a new type definition that is accessible from the symbol :new-type. To 
use the parameters defined from the menu, send the message :transfer-frame 
with the :type keyword set to :new-type. 


External trigger support is provided in the frame grabber software. The second 
BNC connector from the top on the frame grabber paddle board is an external 
trigger. Closing a switch connected to that input starts a framegrab at the 
beginning of the next frame, if you have enabled the external trigger. 

The keyword argument :grab :external-trigger in the :transfer-frame 
message allows you to use this feature under program control. In addition, 
frame grabbers accept the following messages relevant to the external trigger: 


:external-trigger-enable Message 
Returns the state of the external trigger enable. 


:set-external-trigger-enable t-or-nil Message 
Enables or disables the action of the external trigger. The initial state is t. 


:wait-for-external-trigger Message 
Waits for the external hardware trigger to grab a frame. 
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Specifying internal or external sync defines whether the frame grabber or the 
external video source is to provide the sync. 


In external sync mode, which is the default mode, the frame grabber expects to 
lock onto the sync supplied by the incoming video. This can be either from 
composite video supplied on the green input channel or from composite sync 
supplied on the sync input channel. 


In either case, the sync select jumper on the back of the paddle board, near the 
red input jack, has to be in the correct position. The ‘“‘up” position is the correct 
setting for composite video on green. The “down” setting is correct for 
composite sync on the sync jack. If your sync jumper is not set to the correct 
position for your hardware configuration, you will not be able to framegrab. 


In internal mode, the frame grabber ignores incoming sync and instead provides 
the sync for the external video source. This requires that the external video be 
locked onto it. The external video source must have genlock capability if the 
frame grabber is to provide sync. 


To specify external or internal sync, use the following message: 


:Sync-source source Message 
Specifies the source for sync to be used for the framegrab. source can be 
:external (default) or :internal. 


Framegrabbing black-and-white grayscale images presents its own special 
situations that you must consider. To begin with, using color video sources 
without decoders is not recommended because the color subcarrier will be 
visible in the form of a checkerboard superimposed on the grabbed image. To 
avoid the checkerboard effect, you can do one of the following: 

>» Use a black-and-white grayscale video source to begin with. 

> Get a decoder and use one channel (usually the green) of the output. 


> Use a filter to remove the subcarrier. 


Most black-and-white video sources should be hooked to the green input 
because that is where composite sync is accepted. 
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In addition to the messages for color screens described previously, the CAD 
buffer hardware option supports several map modes and messages that are 
unique to this option. These map modes and messages are primarily concerned 
with determining and specifying screen visibility in the unique environment 
that the CAD buffer provides. 
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With the CAD buffer, you can draw on three different objects: an 8-bit color 
screen, a 1-bit overlay screen, and an external overlay array that acts as if it were 
a 1-bit overlay on the color screen. The 8-bit color screen is just like the screen 
available with any other pseudo-color system; it accepts all color messages, uses 
color maps, color ALUs, and color objects. The overlay screen is a 1-bit screen 
that works just like a black-and-white screen, except that you can pick the pair 
of colors it uses and specify the RGB values for both the background and fore- 
ground. The external overlay array is accessed by drawing on a window of the 
8-bit screen with a special ALU, which is described later. 


The seven map modes unique to the CAD buffer control which screens are visi- 
ble at the moment. By changing the map mode, you can control screen visibil- 
ity so that you see one of the following: 


> The overlay screen only 

> The color screen only 

> The color screen with images from the overlay screen 
» 


The color screen with images from the external overlay array 


It is worth pointing out that you can always send drawing messages to any of 
these objects, no matter which ones are visible. 


Before you can do anything with the overlay screen, you need to make it acces- 
sible by sending the message :overlay-screen to the CAD buffer screen. 


:overlay-screen Message 
Returns the overlay screen associated with a CAD buffer screen. To draw on 
the overlay screen, you need to create windows as described in Chapter 2— 
“Color Window System.’ Since the overlay screen shares hardware with the 
8-bit screen, it also shares the messages relating to the state of that screen. 


Example—Make the overlay screen accessible through a variable 
name. 


(defvar *overlay-screen* 
(send (color:find-color-screen) :overlay-screen)) 


With two screens and one monitor in a CAD buffer system, it is up to the soft- 
ware to determine which screen (or screens) can be seen and what colors ap- 
pear on the screen(s). Controlling colors on the 8-bit screen is done by loading 
color maps and manipulating the maps, slots, and map segments just as for any 
other 8-bit pseudo-color screen. Controlling colors on the overlay screen de- 
pends to an extent on the map mode you have selected. Before discussing the 
messages used to set colors on an overlay screen, you should understand the 
effects of the seven unique map modes available for use with the CAD buffer. 
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CAD buffer map modes determine two things: the visibility of each screen and 
the source of the overlay data. Depending on the map mode you select, you can 
see only one screen or the other, or you can see objects you draw on either the 
overlay screen or on the external overlay array superimposed on the 8-bit 
screen. 


There is an important difference between the modes that have the word -with- 
in their name and all other modes. The -with- modes refer to the overlay array, 
not the overlay screen. If you change between -with- and -and- modes, the 
array currently in use is saved, and the 1-bit overlay screen is then updated with 
the data from the array that is appropriate for the new mode (not unlike the way 
different color map images can be written to the color map hardware). 


You can have two overlay images, one visible in the -with- modes and one in 
the -and- modes, that are completely different in every way. There is only one 
8-bit image. 

The CAD buffer supports the following color map modes: 


:8-bit Only the 8-bit screen is visible. All drawing 
Operations and messages appropriate to any 
8-bit screen are available; the screen oper- 
ates just like any other 8-bit, pseudo-color 
frame buffer. You can send drawing mes- 
sages to the overlay screen or the overlay 
array, but they are not visible. 


:Opaque-overlay Only the overlay screen is visible; it there- 
fore has a foreground and a background 
color, which you can specify with messages 
described later. By default, it is a white 
screen (background) with black letters (fore- 
ground). Except for choosing the pair of 
colors, the screen operates like any other 
1-bit screen, and all appropriate drawing op- 
erations are available. Objects you draw on 
the screen in this mode are also visible in 
the -and- modes. 


:8-bit-with-overlay Only the 8-bit color screen is visible. For all 
functional purposes of visibility, this mode 
duplicates the :8-bit mode. 


:8-bit-and-foreground-overlay 
In this mode, the overlay screen is superim- 
posed on the color images for the 8-bit 
screen. To draw objects that appear super- 
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imposed on the color screen, send the 
drawing messages to the overlay screen. 


:8-bit-with-foreground-overlay 

In this mode, the-overlay screen array asso- 
ciated with the -with- modes is superim- 
posed on the color images from the 8-bit 
screen. To draw objects that appear super- 
imposed on the color screen, send the 
drawing messages to the color screen, using 
an ALU created with the array field set to 
:external-array as defined later. 


:8-bit-and-embedded-overlay 
In this mode, the bit from each pixel in the 
overlay screen replaces the most significant 
bit of the pixel data in the 8-bit screen. To 
write to these bits, send drawing messages 
to the overlay screen. 


:8-bit-with-embedded-overlay 
In this mode, the bit from each pixel in the 
-with- array replaces the most significant 
bit of the pixel data in the 8-bit screen. To 
write to these bits, send the drawing mes- 
sages to the color screen, using an ALU 
GLEAtcGe wi tiie thcCearray au cla set .c@ 
:external-array as defined later. 


Determining the overlay color depends on what mode you have selected. If you 
are in :opaque-overlay mode, use the following messages to determine the 
colors of the overlay screen. 


In the following messages, the optional argument control (where included) can 
be used to specify a control register image. See the section “Control Register 
Messages” later in this chapter. 


:foreground-color &optional control Message 
Returns the foreground color specified for the overlay screen. This is the 
color that corresponds to the value of char-aluf for this screen. 


:set-foreground-color flonum-list &optional control Message 
Sets the foreground color for the overlay screen when used in :opaque- 
overlay mode. flonum-list is a list of three floating-point numbers between 
0 and 1.0 that represent the red, green, and blue values for the foreground 
colors. This color specification has no effect in other map modes. 
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:background-color &optional control Message 
Returns the background color specified for the overlay screen. This is the 
color that corresponds to the value of erase-aluf for this screen. 


:Set-background-color /lonum-list &optional control Message 
Sets the background color for the overlay screen when used in :opaque- 
overlay mode. flonum-list is a list of three floating-point numbers between 
O and 1.0 that represent the red, green, and blue values for the background 
colors. This color specification has no effect in other map modes. 


If you are in :8-bit-and-foreground-overlay or :8-bit-with-foreground- 
overlay mode, objects drawn on the overlay screen are visible as opaque 
images superimposed on the color screen. 


You can select from eight colors to be used as the foreground overlay color. The 
following messages determine these colors. 


:Overlay-color &optional control Message 
Returns the color in which objects drawn on the overlay screen will appear. 
The colors can be :red, :green, :blue, :cyan, :magenta, :yellow, 
:black, and :white. By default, the overlay color is white. You can send 
this message to either the 8-bit or overlay screen. 


:Set-overlay-color &optional control Message 
Specifies the color in which objects drawn on the overlay screen will ap- 
pear. The colors can be :red, :green, :blue, :cyan, :magenta, :yellow, 
sblack, and :white. By default, the overlay color is white. You can send 
this message only to the 8-bit screen. 


Embedded-overlay modes replace the most significant bit of the pixel data on 
the 8-bit screen with the bit from the corresponding pixel of the overlay screen. 
To achieve any benefit from these modes, you need to create color maps for 
which the high bit is significant. For example, you could have a color map 
segment in which slots 128-255 were complementary to the colors in slots 
0-127. Setting the overlay bit results in complementing any color being 
displayed in the corresponding pixel region of the 8-bit screen. 


Writing on the overlay screen can be accomplished in two ways. If you send a 
drawing message to a window on the 1-bit overlay screen, the resulting object is 
visible in :opaque-overlay mode and in either of the -and- modes. 


To write to the overlay array visible in the -with- modes, you need to make an 
instance of an ALU in which you specify :external-overlay as the value of the 
:array field of the ALU. Color screens have several arrays associated to them; 
the array field of the ALU object defines which of these screen arrays are used. 
When you specify :external-overlay, the system uses the overlay array instead 
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of the normal 8-bit color screen array. This attribute of the ALU is represented 
by the ALU instance variable :array. For more information, see Chapter 3— 
“Color ALUs.” 


Once you have such an ALU object, pass it as the ALU-argument to any drawing 
message you send to the color screen. The external overlay array, rather than the 
main 8-bit color screen, is changed by the drawing operation. 


Using the -with- modes and the special ALU makes it much simpler to draw 
overlay images with respect to the underlying color images, since you do not 
need to keep track of overlay/color window alignment. If, for instance, you 
want to draw overlays on a window of the color screen with corners selected. 
from the mouse (this kind of window specification is demonstrated in 

Chapter 7—‘‘Color System Tutorial’’), send the drawing messages to the color 
window with your special ALU object and the color system lines everything up 
for you. 


Mouse and screen selection is a little more complicated when you have the 
CAD buffer 8-bit color screen and the 1-bit overlay screen to contend with. 
Normally, the key sequence FUNCTION X switches the mouse back and forth 
between the black-and-white and color screens. However, FUNCTION X is not a 
two-way toggle, but rather steps the mouse through a ring of screens. Since in 
some map modes the 8-bit or the overlay screen might not be visible, it is 
possible that moving the mouse to a window might not have the effect you 
expect. 


The mouse should not normally be switched to an invisible screen; under 
normal circumstances, the mouse must be sent to a visible screen. To determine 
whether a screen is visible at the moment, send the screen a :video-on 
message. If the screen is visible, it returns t. If you give the screen a property of 
:turn-on-video-for-mouse, the screen is made visible when you move the 
mouse to it, such as with the function tv:mouse-set-sheet. 


If you select a window on an invisible screen, the system makes it visible by 
changing the map mode. If for some reason you do not want a window to 
become visible when you select it, you can give the window a property of 
:dont-make-visible-when-selected. 


When switching between the overlay and 8-bit screens, you can give either 
screen the property :set-mouse-sheet-when-selected. This automatically 
sends the mouse to that screen when you expose it. :set-mouse-sheet-when- 
selected accepts the following values: 


:from-overlay Sets mouse-sheet when the 8-bit screen is 
selected. This is the default if you are taking 
the mouse from the overlay screen. 
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:from-parent Sets mouse-sheet when the overlay screen 
is selected. This is the default if you are tak- 
ing the mouse from the 8-bit screen. 


The software that controls mouse and screen visibility and Selection is 
described in full detail in Volume 7 of the Symbolics Lisp Machine documenta- 
tion, Programming the User Interface. 
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Color System Tutorial 

Creating and Using Color Windows 
Making Color ALUs the Easy Way 
Using Software Overlay Effects 
Using Hardware Overlay Effects 


7 
Color System Tutorial 


This tutorial is made up of several examples that demonstrate how to create 
windows on the color system, draw objects on the window, and specify and 
change the colors of those objects. By following the examples and experiment- 
ing with the functions, you will learn to do the following: 


> Create color ALUs of several different types 


> Modify color maps for your own purposes 


>» Change images by manipulating color maps and ALUs 


The examples should be followed in the order given since later examples build 
bE on previous Ones. For example, windows you create in an early example are 
fis used throughout the tutorial. 


While you are working through this tutorial, enter all code in an editor buffer 
that is set to Lisp mode and Common Lisp syntax. To do this, use the com- 
mands Lisp Mode (m-X) and then Set Lisp Syntax (m-X). Select Common Lisp. 
Your mode line should now read Lisp Mode. 


Most examples are cast in the form of functions that you can call from the Lisp 
Listener or from within other functions. This is partly for ease of use later on, 
since once the function is defined, you can type in a function name and perhaps 
a parameter or two to see the effect of the lesson in question. However, it is also 
good programming practice to take advantage of the built-in modularity of Lisp. 


a You are encouraged to experiment with the functions described in this chapter 
by changing the type of ALU, the color values passed to the ALU function, and 
any other parameters that interest you. See how your changes affect the images 

a on the color monitor. 


This tutorial assumes that you have loaded the color system software and the 
color demonstration system software. (Loading the color-demo software en- 
sures that the color system software is loaded.) If you have not already done so, 
load the color demonstration system software as described in Appendix C. 


_— 
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Creating and Using Color Windows 


The simplest way to create a color window if the color demonstration system is 
loaded is to include the following definition in your color program: 
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(defvar *window”* (color:demo-window)) 


This finds or, if necessary, creates a color window and associates it with the 
global variable * window ~*. Most important, this structure finds an existing 
window, if one is available, rather than creating a new window, which uses addi- 
tional frame buffer memory. 


e @ Example—Create a window with edges selected from the mouse. 
Define the function: 


(defun make-color-window-from-mouse 
(&rest options &key (superior (color:find-color-screen :create-p t)) 
&allow-other-keys) 
(apply #’tv:make-window ‘tv:window 
‘blinker-p nil 
‘borders 2 
‘Save-bits nil 
‘expose-p t 
‘label “Demonstration Window”’ 
-edges-from ':mouse 
‘Superior Superior 
options)) 


(defvar *color-window* (make-color-window-from-mouse)) 


Now when you call this function, you can use the mouse to select the bounda- 
ries of the window on the color screen. Be aware, however, that every time you 
call this function, a new window is created. 


ee Example—Create a window with a pale green background written on 
by white letters. 


Define the function: 


(defun make-green-window (&rest options) 
(apply #’make-color-window-from-mouse 
-erase-aluf (send color:color-screen 
-compute-color-alu 
tv:alu-seta O 0.2 0) 


options)) 


(defvar *green-window* (make-green-window)) 


96 7 +» Color System Tutorial 


a 


tions: 
mm » A window with a black background, accessible through:the global 


variable * color-window * 


pe » A window with a pale green background, accessible through the global 
: a variable *green-window* 


The remaining functions in this tutorial take a window as their first argument. 
You should use one of the windows just created as that value. Be sure the win- 
dow you use is exposed before you try to use it. If it is not exposed, you end up 
in the Output-Hold state, waiting for the window to be exposed. Pressing FUNC- 
il TION ESCAPE exposes the window that is waiting to be exposed. 


Making Color ALUs the Easy Way 


Each screen supports a protocol for producing an ALU instance that results in 
the proper color being displayed. Sending the message :compute-color-alu to 


roe 
— You now have two different windows to choose from for the drawing opera- mt 
— a screen returns such an instance. (See the section on ALU messages to screens 


rt in Chapter 4—“‘Color ALUs.”’) Using this method to obtain ALU instances with 
the correct instance variables allows a program to work the same on 8- and 

in 24-bit systems. 

it : 

bom The simplest ALU is one that sets all the fill-data to the desired color. The fol- 
lowing example makes such a color ALU. 

Vt (defvar *orange-alu* (send (send *green-window~ :screen) 

:compute-color-alu 
ee color:alu-x 1.0 0.4 0.0)) 
a | 


The three values following color:alu-x represent the red, green, and blue 
pk values, respectively. These values can be any number between 0 and 1. For the 
nil sake of simplicity, the magic numbers 1.0, 0.4, and 0.0 were used; they specify a 
Ck strong, bright orange in the RGB color model. In reality, you would probably 
oS use the color editor to determine the magic numbers to specify the color you 
rit choose. See Chapter 11—‘“‘Color Editor.’ 
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Example—Draw an orange circle in the middle of the screen. 


To make an orange circle appear on a color window, you need to expose the 
desired window and send the window a message to draw.the object, with the 
ALU as one of the drawing arguments. ena 


This example uses the :draw-filled-in-circle message. (See Appendix B— 
“Graphics Mixin Methods” for more information on drawing messages.) 


1. Define the function: 


(defun orange-dot (window &key (radius (/ (send window :inside-width) 4)) 
(center-x (/ (send window :inside-width) 2)) 
(center-y (/ (send window :inside-height) 2)) 
(alu *orange-alu*) 
(clear t)) 
(when clear (send window :clear-window)) 
(send window :draw-filled-in-circle center-x center-y radius alu)) 


2. Evaluate (orange-dot *green-window”). 


This function assumes you have created * green-window* and 
*orange-alu*. 


The following two examples demonstrate the two ways to change the colors on 
your monitor. You can draw the object with a different ALU, or you can change 
the color map “‘out from under” the object on the screen. Changing the color 
map has advantages and disadvantages: 


On the plus side, it is a fast operation that can give the appearance of dy- 
namic motion to a still image. (See the [Cycle Color Maps] option from the 
menu that appears when you select [Mandelbrot Images] from the color- 
demo menu.) 

On the minus side, the changes affect the whole screen, so to get the 
desired effects, you must carefully control all the pixel values on the screen 
and the color maps. 


Example—Change the visible colors by using different color ALUs. 
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1. Evaluate the form: 


(orange-dot *green-window” :alu (send (send *green-window” :screen) 
‘compute-color-alu tv:alu-seta 
0.0 0.0 1.0)) 
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This changes the orange dot to blue. 
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2. Evaluate (orange-dot *green-window” :alu tv:alu-andca) to erase the blue 
dot. Note that this erases to black, rather than the green background 
color. 


. Evaluate (orange-dot *green-window” :alu (send *green-window” :erase-aluf)) 
to erase the black dot to the same green color as the window back- 
ground. 


Example—Change the visible colors by manipulating the color map. 


1. Define a function to change map segment 1 into a “scaled” version of 
segment 0, where “scaling” multiplies the intensity by some constant: 


(defun scale-color-map (scale &optional (screen (color:find-color-screen))) 
(loop for slot from 0 below (send screen :color-map-description) 
do 
(multiple-value-bind (r g b) (Send screen :read-managed-map slot 0) 
(send screen :write-managed-map slot (“ r scale) (* g scale)(* b scale) 1))) 
(send screen :new-color-map)) 


2. Evaluate (scale-color-map 0.5) to change the scale to one half the normal 
intensity. Note that nothing changes because you changed map 
segment 1 while you are still looking at map segment 0. 


. Evaluate (send color:color-screen :set-map-mode nil 1) to shift the primary 
map segment to map segment 1. 


4. Evaluate the form: 


(loop repeat 100 do 
(send color:color-screen :set-map-mode nil 1) 
(send color:color-screen :set-map-mode nil 0)) 


This causes the screen to flash for a while, ending with the screen using 
the normal color map. 
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ee Example—Use :masked-bits to transfer a 1-bit image to the color 
screen. 


Because bitblt is defined to copy bit-wise, it is not normally useful to simply 
bitblt a black-and-white image to a color screen. 


1. Evaluate the form: 
(send *green-window” :bitblt tv:alu-seta 200 200 tv:hes-gray 0 0 0 0) 
The result is a striped green pattern, not at all like tv:yhes-gray when 
seen on a black-and-white screen. 
2 Evaluate the form: 


(send *green-window* :draw-1-bit-raster 200 200 tv:hes-gray 0 0 0 0) 
This is the easy way to correctly copy a 1-bit image to a color screen. 


3. Define the variable and function: 


(defvar *copy-bits-alu* (make-instance ‘color:general-sc-color-alu 
‘array :masked-bits 
‘fill-data -1 :plane-mask -1 
:alu tv:alu-seta)) 
(defun fast-draw-1-bit-raster (window width height raster fx fy tx ty) 
-- this is faster, but possibly not as pretty as :draw-1-bit-raster 
(send window :draw-rectangle width height tx ty (send window :erase-aluf)) 
(send window :bitblt *copy-bits-alu* width height raster fx fy tx ty)) 


4. Evaluate (fast-draw-1-bit-raster *green-window~ 200 200 tv:hes-gray 0 0 0 0). 


Copying a 1-bit image to a color screen is actually accomplished by 
using the :masked-bits and :not-masked-bits specifications to the 


:array instance variable of color ALUs. For various reasons, you might 


not want to use :draw-1-bit-raster. 


Step 4 has the same end result as step 2, except the window “‘flashes” 
more in the process. 


Using Software Overlay Effects 


This section demonstrates how to set up the color map segment so that display 


objects can be written with replacement and transparent overlay effects. Note 
that this is a software technique and is not related to the use of the hardware 
overlay effects. Hardware overlay is demonstrated in the section “Using Hard- 
ware Overlay Effects” of this chapter. 
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The basic idea in using software to create overlay effects is to partition the bit 
planes into two or more independent bit fields and to set up the color map to 
give the desired color effects to each bit field. This technique is normally used 
only in pseudo-color mode and is limited to the number of bit planes available, 
which is normally 8. 


The plane-mask field of a color ALU is used to restrict the ALU to writing only 
on certain bit fields. 


Example—Use software to simulate replacement overlays. 


The following sketch is of three sets of 1-bit deep objects, residing on the first 
three memory planes corresponding to pixel values of 1, 2, and 4. For visual 
clarity, each set of objects is assigned a unique primary color. Objects on plane 0 
are red, objects on plane 1 are green, and objects on plane 2 are blue. 


color map displayed 
entry # color red green blue 
O black 0 0 0 
1 red 1.0 0 0 
2 green O 166) 0 
) blue 0 0 1.0 


The sketch is incomplete because it does not specify what objects are visible if 
several objects overlap. Suppose you want the blue objects to always appear in 
front of any red or green objects, and green objects to always appear in front of 
any red objects. You might set the color map segments as follows (disregard the 
other five memory planes): 


color map displayed 
entry # color red green blue 
O black 0 0 0 
1 red 1.0 0 0 
2 green O 150 O 
3 green 0 0 0 
4 blue 0 0 1.0 
5 blue 0 0 1.0 
6 blue 0 0 1.0 
gf blue 0 0 LO) 


1. Define the following function to set the color maps as specified in the 
sketch. 
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(defun load-replacement-map (&key (screen (color:find-color-screen)) 
(segn 1) 
) 
(loop with segment-size = (send screen -color-map-description) 
for i from 0 below segment-size 


as (redv grnv bluv) = (cond ((<i1)’( 0 O 0Q)) 

(e220 Ors 0) 

(1A) 280120 20)) 

(178) (004120) 

(t (COA O1-0))) 
do 

(send screen :write-managed-map i redv grnv bluv segn) 

finally 


(send screen :new-color-map) 


)) 


Note that this map follows the convention of having black at slot 0 and 
white in the last slot, so naive programs (such as default windows) look 
right. Also note that the convention is to use map segment 1| for non- 
standard color maps. 


2. Evaluate (load-replacement-map) to load the screen with this map. 


3. Evaluate (send (color:find-color-screen) :set-map-mode :8-bit 1) to make it the 
current map segment. 


4. Define a function that creates ALUs that correspond to the color map. 
(defun replacement-alu (alu color) 


‘let the alu be either a fixnum or a color alu to be reused 
(unless (instancep alu) 
(setq alu (make-instance ‘color:general-sc-color-alu 
‘alu alu :plane-mask -1 :fill-data -1))) 
(send alu :set-fill-data 
(send alu :set-plane-mask 
(selector color eq 
(:red #01) 
(:green #02) 
(:blue #04) 
(t (error “Unknown color -A specified” color))) 
)) 


alu) 
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— 5. Evaluate (send *green-window~ :clear-window). 
The result is not a cleared window because *green-window* has a | 
—_ nonstandard erase-aluf, which does not OPoleT cic a black (or green) | 
_ background with this color map. 
DE 6. Evaluate (send *color-window* :clear-window). 
Low 
7. Evaluate the form: 
— (send *color-window* :draw-rectangle 200 200 20 20 
(replacement-alu tv:alu-seta :red)) 
iT This draws a red rectangle in the window. 
oS 8. Evaluate the form: 
iE 
bow (send *color-window* :draw-filled-in-circle 50 50 100 
(replacement-alu tv:alu-seta :blue)) 
Lie 
Low This occludes part of the red rectangle with a blue circle. 
— 9. Evaluate the form: 
rx (send *color-window* :draw-triangle 5 5 300 5 200 100 
ae (replacement-alu tv:alu-seta :green)) 
Lit | 
Pa This draws a green triangle. Note that the triangle appears in front of 
oie: the red but behind the blue. 
lit | 
10. Evaluate the form: | 
| 
— (send *color-window* :draw-rectangle 160 160 0 0 | 
biom (replacement-alu tv:alu-andca :blue)) 
—s This erases the blue circle. Note that the previously occluded green and | 


hon red parts of the window reappear. A larger area than just the circle was 
erased, but using draw-rectangle is much faster than draw-triangle. 
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ee Example—Use software to simulate transparent overlays. - 


This example uses pseudo-color mode or 8-bit mode. You can simulate a trans- 
parent overlay on a direct color screen too, but it will be used in 8-bit mode. - 


This example builds a special color map, creates ALUs that are appropriate to 
use with this map, and draws some simple pictures. The plane-mask of color 
ALUs is used to isolate a 2-bit overlay from a 6-bit picture. 


The following sketch is of a color map where the 6 lowest-order bits determine 

the intensity and the 2 highest-order bits determine the color. — 
OOxXxxxx Makes a red gray-scale value a 
O1xXxxxxx Makes a green gray-scale value _™ 
10xxxxxx Makes a blue gray-scale value — 
1L1b.0.0,0;0.0.6 Makes a gray gray-scale value 
The 2 highest-order bits are effectively a transparent overlay that determines the _— 


color of the underlying picture defined by the 6 lowest-order bits. In a color 
| q map such as this, the bit fields have an interesting interpretation, so it is some- * 
| times desirable to modify only some bits of the pixel. For example, it might be _ 
desirable to change the color of an area to blue without affecting the intensity. 


1. Define a transparent color map: 


(defun transparent-color-map (&optional (screen (color:find-color-screen :create-p t)) 
| (segn 1)) 
aa i | -- this defines a nonstandard color map in color map segment #1 of the screen _— 
| -- the 6 lowest-order bits determine the intensity, and the high order 
a : ‘- two bits define the hue, which can be red, green, blue, or gray 
i | (loop for slot from O to 63. 7 _— 


as intensity = (/ slot 63.0) 
do 
| --- the red part 
i | | (send screen :write-managed-map slot intensity 0 0 segn) 
| " ‘-- the green part 
(send screen :write-managed-map (+ slot 64.) 0 intensity 0 segn) 
‘-- the blue part 
(send screen :write-managed-map (+ slot 128.) 0 0 intensity segn) 
--; the gray part 
ieieet (send screen :write-managed-map (+ slot 192.) intensity intensity intensity segn) 
get finally (send screen :new-color-map) 


i | )) 


SS 
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2. Define a function to create ALUs appropriate to this map: 


(defun transparent-alu (alu intensity hue) 
;; this function understands the semantics of the above 
‘- “transparent” color map. Pass in an old alu, intensity, and’color 
;; If either intensity or hue is NIL, set the plane mask to not 
;; change that part of the encoded color. 


‘let the alu be either a fixnum or acolor alu to be reused 
(unless (instancep alu) 
(setq alu (make-instance ‘color:general-sc-color-alu 
‘alu alu :plane-mask -1 :fill-data -1))) 
(let* ((plane-mask (logior (if intensity #077 0) 
(if hue #0300 0))) 
(val (round (max 0 (min 63 (* (or intensity 0) 64.))))) 
(pixel (selector hue eq 
(nil val) 
(:red val) 
(:green(+ val 64)) 
(:blue(+ val 128)) 
(gray (+ val 192)) 
(t (error “-A is an invalid hue for the transparent color map” hue)) 
)) 
(send alu :set-fill-data pixel) 
(send alu :set-plane-mask plane-mask) 
alu)) 


¢ 


3. Evaluate (transparent-color-map) to load the transparent map. 


4. Evaluate (send (color:find-color-screen) :set-map-mode :8-bit 1) to make it the 
current map segment. 


Now that the screen is using a nonstandard color map, calling 
:compute-color-alu with R,G,B values does not give the intended 
result; the ALUs it computes are still based on the standard color map. 
By passing a single numeric parameter to the :compute-color-alu 
message, you can specify pixel values directly: 


(send (color:find-color-screen) :compute-color-alu tv:alu-seta #0340) 


However, it is better to isolate the knowledge about such “transparent” 
color maps into a function such as transparent-alu. 


Using Software Overlay Effects 


. Evaluate (defvar *mid-blue-alu* (transparent-alu tv:alu-seta 0.5 :blue)) to de- 
fine a mid-blue ALU. 


. Evaluate (orange-dot *green-window”* :alu *mid-blue-alu*) to draw a mid- 
blue circle. coe 
Of course, by now your “green” window is not green anymore, and 
“orange dot” is not too representative a name either, but the point of 
this exercise should be clear: by manipulating the color maps, you can 
change the colors of images already drawn on the screen. 


. Evaluate (send (color:find-color-screen) :set-map-mode :8-bit 0) to reset the 
screen back to using the standard color map. What happened to your 
mid-blue circle? 


. Evaluate (send (color:find-color-screen) :set-map-mode :8-bit 1) to resume 
using the transparent map. 


Example—Change the color information by reusing ALUs rather than 
creating new ALUs. 


The following example assumes the function transparent-color-map has 
been called. temp-alu is used as a scratch ALU rather than consing a new one 
each time. 


1. Define a scratch ALU that will be modified and reused in subsequent 
steps. 


(defvar temp-alu (color:sc-fill-alu -1 -1)) 


2. Draw a light gray rectangle. 
(send *green-window~ :draw-rectangle 100. 100. O O (transparent-alu temp-alu 0.4 
:gray)) 
3. Draw a circle of half-intensity full red. 


(send *green-window™~ :draw-filled-in-circle 50. 50. 50. (transparent-alu temp-alu 0.5 
:red)) 


4. Draw a bright line over the rectangle and circle while preserving the 
hue (2 highest-order bits) but setting the intensity (the 6 lowest-order 
bits). 


(send *green-window* :draw-line 0 0 100. 100. (transparent-alu tv:alu-seta 1.0 nil)) 
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5. Draw a blue rectangle, preserving the intensity information. 


(send *green-window~ :draw-rectangle 50. 50. 0 O (transparent-alu tv:alu-seta nil 
:blue)) 


6. Evaluate the form: 


(let* ((Scr (color:find-color-screen)) 
(default-mode (send scr :default-map-mode))) 
(send scr :set-map-mode default-mode 0)) 


This restores the normal color map to use. Of course, this is the ““gen- 
eral”’ way of doing it, which is appropriate for a program to use. If you 
were just typing commands, you would do something ad-hoc such as 
(send color:color-screen :set-map-mode :8-bit 0). However, it is recom- 
mended that programs use the more general forms, so they are more 
likely to work under novel circumstances. 


Using Hardware Overlay Effects 


This section of the tutorial is useful only if you have hardware with overlay 
capabilities. Use (send (color:find-color-screen) :map-modes) to be sure that is the 
Case 


ee Example—Use hardware replacement overlays. 


In replacement overlay mode, color map segment 7 + | is substituted for color 
map segment 7 if any overlay bits are on. This example uses the same replace- 
ment color map as in the simulated software replacement maps in the previous 
example, but since the overlay is implemented in hardware, it can be used in 
conjunction with any normal picture. 


1. Define the functions: 


(defun setup-hardware-replacement (&optional (screen (color:find-color-screen))) 
(send screen :set-map-mode :8-bit-replacement-overlay O 0) 
(send screen :standardize-color-map) ;standardize the normal part of the map 
(load-replacement-map) ;defined in a previous example 


) 


; generates an ALU which will not affect the overlay bits 
(defun non-overlay-alu (alu r g b &optional (screen (color:find-color-screen))) 
(let ((alu (Send screen :compute-color-alu alu r g b))) 
(multiple-value-bind (nil nil p s) 
(send color:color-screen :map-mode) 
(send alu :set-plane-mask (deposit-byte 0 p s -1))) 
alu)) 


Using Hardware Overlay Effects 


- generates an alu affecting only the overlay bits, using the 
- replacement-color-map from the example 
(defun overlay-alu (alu color &optional (screen (color:find-color-screen))) 
(let ((alu (replacement-alu alu color))) cecal 
(multiple-value-bind (nil nil nil nil overlay-p overlay-s) 
(send screen :map-mode) 
(send alu :set-plane-mask 
(deposit-byte 0 overlay-p overlay-s (send alu :plane-mask))) 
(send alu :set-fill-data (Ish (send alu :fill-data) overlay-p))) 
alu)) 


- generate N random triangles, with an overlaid green dot in the 
; center of each. 
(defun random-triangle-with-dot (window &optional (n 1) (dot t)) 
(send window :clear-window) 
(loop with screen = (send window :screen) 
and width = (tv:sheet-inside-width window) 
and height = (tv:sheet-inside-height window) 
repeat n 
do 
(let ((xO (random width)) (x1 (random width)) (x2 (random width)) 
(yO (random height)) (y1 (random height)) (y2 (random height))) 
(send window :draw-triangle 
xO yO x1 y1 x2 y2 
(non-overlay-alu tv:alu-seta 
(random 1.0) (random 1.0) (random 1.0) 
screen)) 
(when dot 
(send window :draw-filled-in-circle 
(7 (+ x0 x1 x2) 3) 
(/(+ yO y1 y2) 3) 
4 


(overlay-alu tv:alu-seta :green screen) 


))))) 


2. Evaluate (setup-hardware-replacement) to get the screen ready. 


3. Evaluate (random-triangle-with-dot *color-window* 20) to fill the window 
with random triangles. Note that all the green dots appear in the fore- 
ground, regardless of the triangles drawn under it. 


4, Evaluate (send (color:find-color-screen) :set-map-mode :8-bit) to make the 
dots disappear. 
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5. Evaluate (send (color:find-color-screen) :set-map-mode :8-bit-replacement- 
overlay) to make the dots reappear. 


6. Evaluate the form: 


(send *color-window~ :draw-rectangle 
(send *color-window~ :inside-width) 
(send *color-window”~ :height) 

00 
(overlay-alu tv:alu-seta :red)) 


This slides a red background between the triangles and the dots. 


7. Evaluate the form: 


(send *color-window” :draw-rectangle 
(send *color-window”~ :inside-width) 
(send *color-window™ :height) 

00 
(overlay-alu tv:alu-andca :red)) 


This erases the red background, leaving the dots and the triangles as 
they were originally. 


Example—Use hardware transparent overlays. 


In transparent overlay mode, color map segment 7 is substituted for color map 
segment 0 if any overlay bits have value 7. This example defines a “darker” and 
a “lighter” color map, so that overlays using the alternate color maps make it 
appear that the underlying picture is being viewed through a transparent gel. 


1. Define the functions: 


(defun setup-hardware-transparency (&key (screen (color:find-color-screen))) 
(send screen :set-map-mode :8-bit-transparent-overlay O 0) 
(send screen :standardize-color-map) 
(loop for slot from O below (send screen :color-map-description) 
do 
(multiple-value-bind (r g b) (send screen :read-managed-map slot 0) 
(send screen :write-managed-map slot 
(762) (7g 2) (7b 2) 
1) 
(Send screen :write-managed-map slot 
(+ r(7(- 1.0 r) 2))(+ g(/ (- 1.0 g) 2)) (+ Db (/ (- 1.0 b) 2)) 
2))) 


(send screen :new-color-map)) 


Using Hardware Overlay Effects 


(defun overlay-box-alu (alu color &optional (screen (color:find-color-screen))) 
-let the alu be either a fixnum or a color alu to be reused 
(unless (instancep alu) 
(setq alu (make-instance ‘color:general-sc-color-alu « 
‘alu alu :plane-mask -1 :fill-data -1))) 


(send alu :set-plane-mask _. 
(send alu :set-fill-data 
(Ish (selector color eq 
(:dimmer 1) — 
(:brighter 2) 


(t (error ‘‘-a isn’t a known color” color))) 
(send screen :overlay-description) 


| ))) 
i alu) 


| 2. Evaluate (setup-hardware-transparency) to set up the screen. 


| 3. Evaluate (random-triangle-with-dot *color-window* 20 nil) to fill *color- 
ib window* with triangles, but no dots. 


This intensifies an area of the window. 


a ea 


mit 5. Evaluate the form: 


4 (send *color-window* :draw-filled-in-circle 200 200 100 


etl | 4, Evaluate the form: 
| Hi (send *color-window* :draw-filled-in-circle 100 100 100 
ce (overlay-box-alu tv:alu-seta :brighter)) 
(overlay-box-alu tv:alu-seta :dimmer)) . 
cles overlap, the original intensity is restored. This is because color map 


ii 

| This darkens an area. Note that where the “brighter” and “darker” cir- 
1 | 
segment 3 is the same as color map segment 0. 


6. Evaluate the form: 


(send *color-window* :draw-filled-in-circle 100 100 100 
(overlay-box-alu tv:alu-andca :brighter)) 


This removes the bright circle. 


" 
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9 Color Hardware Options 
Standard Color System 
Chroma Color System 
Broadcast-Resolution Color System 
CAD Buffer Color System 
CAD Buffer II Color System 
Digitizing Frame Grabber 


8 
Terms and Features 


This chapter introduces the terms that describe the hardware features of the 
various color systems. 


A color system consists of a Lisp Machine with the addition of color memory, a 
color controller, and a paddle board. The possible variations of color controller 
and paddle board determine what features are supported. To find what features 
are supported by your color system, refer to Chapter 9—‘‘Color Hardware Op- 
tions” for the section that describes your color system. 


For specific information about installation procedures and the hardware compo- 
nents, see the document Color Graphics Hardware Installation Guide. 


Hardware Features 


Frame buffer 
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A frame buffer stores one or more frames of video information. One value is 
stored in the frame buffer for every pixel in the frame. In simple frame buffers, 
such as the frame buffer associated with the Symbolics console, the stored value 
can be as small as one bit, which can represent only two states, such as black 
and white. More complex frame buffers, especially those designed for the stor- 
age of color information, store a greater number of bits for each pixel. Some 
Symbolics frame buffers can store up to 32 bits for each pixel on the screen. 


A frame buffer can be designed for the display of information (such as the CAD 
buffer), the capture of information (such as the frame grabber), or both. 


All Symbolics frame buffers plug directly into the host processor’s main 
memory bus and do not require additional floorspace or racks. 


Resolution 


Resolution is usually specified as the number of pixels that can be stored in one 
frame and is designated as the number of pixels per line by the number of 
scanlines per frame. The most common resolutions are high resolution (1280 x 
1024) and NTSC resolution (640 x 480). Most Symbolics frame buffers support 
at least two resolutions. 


Image memory board 
(optional) 


$ 
Image memory board 


(optional) 


mm ce = 9 
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Image memory board 
(optional) 


Genlock Composite 
board Sync or 
(optional) Video 


. Figure 8.1 7\;pical color system overview 


Color controller 


The color controller board interfaces to the CPU’s Lbus and controls the opera- 
tion of the color system. It is made up of several independent functions: 


| Ve > The line index tables and control registers, which control the scanning of 
| memory 
i . 

| > The programmable sync generator 


u | > The hardware cursor (only on a high-resolution color system with a high- 
rat resolution paddle board) 


Color controllers are of three types: the standard, CAD buffer, and frame grab- 
ber color controllers. The standard color controller is used by the high- 
resolution, chroma, and broadcast-resolution color systems. The CAD buffer, 

i CAD buffer II, and frame grabber color systems have color controllers that can- 
not be used with other color systems. 
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Line index table 


The line index table (LIT) is a hardware array of pointers to the beginning and 
ending locations of each scanline in color memory. The LIT is accessed sequen- 
tially, making it possible to store scanlines in arbitrary locations in color mem- 
ory. By using the LIT to point to scanlines, you can pan and zoom individual 
scanlines. (See “Line Index Pan and Zoom Messages” in Chapter 6—‘‘Additional 
Color System Features.’) 


Global pan registers 


Global pan registers select the offset into color memory where output scanning 
begins. Pan can be set independently in x and y. Pan in x adds an offset to the 
Starting address in each entry of the LIT. Pan in y sets the first scanline to be 
displayed. 


Global zoom registers 


Global zoom registers determine the number of times a pixel is replicated on 
video output. A replication factor of 7 replicates pixels 7 times, which has the 
effect of zooming the picture by a factor of + 1. A replication factor of 0 (the 
default value) causes no replications, hence the pixel appears only once. Zoom 
can be set independently in x and y. Pixels are replicated from the origin of the 
screen, which is in the upper-left corner. 


All four pan and zoom parameters (xpan, ypan, xzoom, yzoom) can be set inde- 
pendently and controlled globally using the messages documented in 
Chapter 6—“‘Additional Color System Features.” 


The zoom protocols can be implemented in software without hardware support 
by using a window mixin. The mixin can be used with almost any window, 
including the black-and-white screen. See Chapter 6-—“‘Additional Color System 
Features. 


Access modes 


The window system accesses the pixels in the frame buffer by using one of 
three access modes: pixel mode, packed mode, or fill mode. You usually do not 
have to worry about access modes because the window system chooses the best 
mode for the given operation. 


Pixel mode writes a 32-bit color pixel into color memory 8 bits at a time 
for each of the three color planes. Pixel mode works properly with 8-bit 
color systems but writes only one pixel’s worth of data (8 bits). This mode 
is useful when many different colors need to be read or written to all 32-bit 
planes. It is the most general mode for reading and writing a single pixel. 
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Packed mode writes 4 bytes into four sequential locations of one color 
board. This mode is useful when only 8-bit planes (red, green, blue, or 
overlay planes) are being accessed. 


Fill mode writes 32 sequential pixels in a single operation as a single word 
under the control of a mask. This mode is useful for clearing the screen 
rapidly or for writing a pattern of a single color to a contiguous area, such as 
when a character font is written to the color screen. 


Hardware cursor 


A 64 x 64 pixel cursor is supported by hardware in a high-resolution color sys- 
tem with a high-resolution color paddle board. See Chapter 6-— “Additional 
Color System Features” for the software messages that control the hardware 
cursor. 


Sync generator 


The sync generator generates horizontal, vertical, and other sync signals. The 
sync generator is programmable and supports a number of sync formats. For 
information about creating a standard or nonstandard sync program or for infor- 
mation about creating your own sync program, see Appendix A. 


Genlock 


The genlock option synchronizes a high-resolution, chroma, or broadcast- 
resolution system to an external video signal. The genlock option is frequently 
used in a video production environment. 


Alpha channel 


The alpha channel is a fourth video output channel. It carries 8 bits of matting 
information in addition to the color information. This information is carried to a 
video switcher, which then combines it with another image to form a compos- 
ite image. The process of combining images by specifying a key value per pixel 
is called alpha keying. 


The alpha channel can also be used to drive a black-and-white monitor. 


Chroma key output 


Chroma key hardware allows an internally created image to be combined with 
an image from an outside video source. Chroma key output, like alpha keying, 
uses the fourth video channel; however, unlike alpha keying, which relies on 
each pixel to contain the switching data, chroma keying is controlled by the 
color in the frame buffer. 
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Black-level switch 


The black-level switch forces video on the R, G, and B channels to black. The 
black-level switch is similar to chroma keying except that it affects the R, G, and 
B channels rather than the alpha channel. It is normally used in conjunction 
with chroma keying. 


Overlay 


An overlay plane is an additional bit plane of image memory that can be used to 
superimpose an image over the main frame buffer image without rewriting or 
changing the data in image memory. The overlay plane can be set for two 
modes: transparent mode, in which the main frame buffer image can be seen 
through the overlay image, or replacement mode, in which the main frame 
buffer image is obscured by the overlay image. 


You can simulate transparent and replacement overlays without special hard- 
ware support by using the color map (either on an 8-bit system or on a 24-bit 
system in 8-bit mode) to arrange for the bits in the pixel to be interpreted in the 
appropriate manner. Techniques for this are detailed in the Chapter 7—“Color 
System Tutorial.” 


Map modes 


Map modes determine how pixel data are interpreted by the color map. The 
mode in which the system is running is determined by what bits are fed to the 
color maps and how the color maps are configured. Typically, the address input 
to the color map is composed of some bits from the controller, some bits gener- 
ated by the overlay logic, and some bits derived from the frame buffer. The 
following are the actual color map sizes: 


System Color map size Number of address bits 
Chroma 1024 10 
High-resolution 1024 10 
Broadcast 4096 12 
Cad buffer 256 8 
Cad buffer II 1024 10 


CAD buffer map modes are different. They are described under “CAD buffer 
map modes.’ 


Hardware Features 


8-bit 

The color maps are broken up into a certain number of blocks of 256-byte 
tables. Four bits from the control register choose which 256-byte table is se- 
lected, and 8 bits from the memory board select the value in the selected table. 
If more than 8 bits per pixel are available, the color controller can select which 
of them provides the input to the color maps, and the extra bit planes can be 
used to implement multiple buffering. 


8-bit replacement overlay 


The color maps are broken up into a certain number of blocks of two 256-byte 
tables. The top 8 bits from the memory board are designated as the overlay bits, 
and the switching logic chooses 8 bits of the remaining 24 to enter the color 
maps. Three bits from the control register select which block of tables to access, 
and the overlay bits select which of the two 256-byte tables is selected. 


8-bit transparent overlay 


The color maps are broken up into a certain number of blocks of 256-byte 
tables. This mode resembles 8-bit with replacement overlay, except that the 4 
bits that select the table come from the overlay bits, not from the control regis- 
ter; 


12-bit 

This mode is available only on the broadcast-resolution system. The color maps 
are organized as one continuous block, and 12 bits access one of the 4096 
addresses. This mode supports double-buffered operation. 

24-bit 

This mode resembles 8-bit mode except that 24 bits are fed to the color maps. 
The red, green, and blue values are fed to separate color maps. 

24-bit replacement overlay 


This mode resembles 8-bit with replacement overlay except that 24 bits are fed 
to the color maps. The red, green, and blue values are fed to separate color 
maps. 


24-bit transparent overlay 


This mode resembles 8-bit with transparent overlay except that 24 bits are fed to 
the color maps. The red, green, and blue values are fed to separate color maps. 
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CAD buffer map modes 


The CAD buffer supports a limited 1-bit overlay plane, for which three types of 
overlay are possible: 


Opaque overlay, where the 2-color overlay screen completely replaces 
the 256-color regular screen. 


Foreground overlay, which places a primary or a secondary color over a 
regular screen in the background. This is similar to replacement overlay on 
other types of color screens, except that the overlay colors are strictly lim- 
ited to black, white, red, green, blue, cyan, yellow, and magenta. Only one 
color is displayed at a time. 


Embedded overlay, which substitutes the high-order bit of the regular 
screen and embeds the overlay plane in the normal image. This is similar to 
transparent overlay on other types of color screens except there is only one 
color map segment. 


Hardware Features 
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Color Hardware Options 


This chapter lists the hardware features of each of the color system options. 


High-Resolution Color System 


Ae) 


The high-resolution color system is a flexible, high-performance color display 
option that plugs directly into the main memory bus. It supports configurations 
that allow from 8 to 32 bits per pixel, making it of maximum utility in applica- 
tions where there is a need for more than 8 bits per pixel. This includes video 
animation, slide making, paint, graphics, and image processing. The high- 
resolution color system is compatible with the genlock option, allowing it to 
operate in a live video environment and in conjunction with professional video 
recording equipment. 


Resolution is fully programmable and can run at a wide range of frame, field, 
and line rates. The most common resolutions are NTSC resolution (640 x 480) 
and high resolution (1280 x 1024). 


A high-resolution color system can have from one to four color memory boards. 
Each board contains 2 Mbytes of color memory and contains 8 one-bit planes. 
The following configurations are variations of the high-resolution color system: 


8-bit. The single color memory board provides 8-bit pseudo-color. 


16-bit. This configuration can be programmed to run as two 8-bit systems, 
allowing for double-buffered operation. 


24-bit. Three color memory boards provide 24-bit RGB color. This config- 
uration can be programmed to run as three 8-bit systems, allowing for 
triple-buffered operation. 


The high-resolution color system supports the following features: 
Two modes of operation: 


:8-bit 
:24-bit 


Programmable resolution 
Line index table 
10-bit DACs 


Table 9.1 Color system feature comparison 


High- 
Resolution Digitizing 
High- System with Broadcast- — ._ Frame 
Resolution | Chroma Resolution CAD Buffer CAD Bufferll Grabber 
FEATURES System Paddle Card System System System System 
_— 
> Memory 81-bit planes 81-bit planes 24 1-bitplanes 81-bitplanes 81-bitplanes 24 1-bit plane” 
onlmemory on1memory plus 8 bits plus 1 bit plus 2-bit on the ; 
board or board or overlay on 1 overlay onthe overlay onthe controller 
24 1-bit planes 8 1-bit planes ™emory board controller controller 
on3 memory plus 8 bits 
boards overlay on 2 
; memory 
) boards 


ai or 
24 1-bit planes 
on 3 memory 


~~ boards or 
24 1-bit planes : 
plus 8 bits 
overlay on 4 
memory 
boards.* 7 
| > Video Format 
e RS-343A (HIRES) Yes Yes No No Yes No 
rF NTSC Yes Yes Yes No Yes Yes 
PAL Yes Yes Yes No Yes Yes 
CAD buffer No No No Yes Yes No 


Resolution 1280x1024 1280x1024 864 x 582 1024x1024 1280x1024 
Programmable 
up to— 


Pan & Zoom Support 
Keying Support 
Overlay Support 
Genlock Support 
Type of DAC 


*The 8 overlay bits must be dedicated to overlay. No switching without reconfiguring the machine. 


**Horizontal pan is supported in 32-pixel increments. Vertical scrolling is line by line. Zoom ts not supported. 
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Hardware pan and zoom 
Hardware cursor 


Dynamically selectable color maps stored in hardware: 1K-color maps in 
4 color map segments Bes 


Chroma Color System 


The chroma color system is the same as the standard high-resolution system, 
which it replaces, except that it has a chroma paddle board instead of the stan- 
dard high-resolution color paddle board. 


Like the standard high-resolution color system, the chroma color system is of 
maximum utility in applications where there is a need for more than 8 bits per 
pixel. This includes video animation, slide making, paint, graphics, and image 
processing. The chroma color system is compatible with the genlock option, 
allowing it to operate in a live video environment and in conjunction with pro- 
fessional video recording equipment. 


Resolution is fully programmable and can run at a wide range of frame, field, 
and line rates. The most common resolutions are NTSC resolution (640 x 480) 
and high resolution (1280 x 1024). 


A chroma color system can have from one to four color memory boards. Each 
board contains 2 Mbytes of color memory and contains 8 one-bit planes. The 
following configurations are variations of the chroma color system: 


8-bit. The single color memory board provides 8-bit pseudo-color. 


8 +8. Two color memory boards provide 8-bit pseudo-color with overlay 
and alpha channel capabilities. 


16-bit. This configuration can be programmed to run as two 8-bit systems, 
allowing for double-buffered operation. 


16+8. The three color memory boards provide overlay or alpha channel 
capabilities. Two color memory boards can be programmed to run as two 
8-bit systems, allowing for double-buffered operation with overlay or alpha 
channel capabilities. 


24-bit. Three color memory boards provide 24-bit RGB color. This config- 
uration can be programmed to run as three 8-bit systems, allowing for 
triple-buffered operation. 


32-bit. The four color memory boards provide 24-bit RGB color with over- 
lay or alpha channel capabilities. This configuration can be programmed to 
operate as three 8-bit systems, allowing for triple-buffered operation with 
overlay and alpha channel capabilities. 


Chroma Color System 


The chroma paddle board supports the following features: 
Six map modes: 

:8-bit 
:8-bit-replacement-overlay 
:8-bit-transparent-overlay 
:24-bit 
:24-bit-replacement-overlay 
:24-bit-transparent-overlay 


Double-buffered 16-bit operation 
Triple-buffered 32-bit operation 


Hardware overlay (allowing 16- and 32-bit pixels in pseudo-color and direct 
color modes, respectively) 


Programmable resolution 
Line index table 

8-bit DACs 

Hardware pan and zoom 


Dynamically selectable color maps stored in hardware: 1K color maps in 
4 color map segments. 


Chroma key output 
Alpha key output 


Black-level switch 


Broadcast-Resolution Color System 


The broadcast-resolution color system contains one color memory board and 
provides 32 bits of information per pixel at NTSC RS-170(A) or PAL resolution. 
The color memory board contains 2 Mbytes and contains 32 one-bit planes of 
pixel information. The system can run as 24-bit RGB color or can be pro- 
grammed to run as a pseudo-color system, in which up to four frames can be 
stored in image memory for rapid display (quad-buffering). 


The broadcast-resolution color system is of maximum utility in graphics applica- 
tions where there is a need for greater than 8 bits per pixel and where broadcast 
resolution (640 x 480) is acceptable. This includes video animation, slide mak- 
ing, paint, graphics, and image processing. The genlock option allows the 
broadcast-resolution system to operate in a live video environment and in con- 
junction with professional video recording equipment. 
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The broadcast-resolution color system supports the following features: 


Seven map modes: 
:8-bit 
:8-bit-replacement-overlay 
:8-bit-transparent-overlay 
:12-bit 
:24-bit 
:24-bit-replacement-overlay 
:24-bit-transparent-overlay 
Quad-buffered 8-bit operation 
Double-buffered 12-bit operation 
Hardware overlay 


Line index table 


Hardware pan and zoom 
8-bit DACs 


Dynamically selectable color maps stored in hardware: 4K color maps in 
16 color map segments 


Chroma key output 
Alpha channel 


Black-level switch 


CAD Buffer Color System 


The CAD buffer is a single-board frame buffer that occupies only one backplane 
slot. It offers a flicker-free, 60-Hz, noninterlaced display that makes it ideal for 
computer-aided design and engineering, simulation, command and control 
applications, and any other application where the quality of the screen image is 
important. 


Resolution is fixed at 1024 x 1024 noninterlaced. You can program the board to 
run low-resolution, noninterlaced monitors. 


The CAD buffer allows for 8 bits of color and 1 bit of overlay. Its 8-bit color 
cannot be upgraded to 24-bit color. 


il 


The CAD buffer has several limitations. It does not support zoom, pan, genlock, 
or chroma key output. Because the CAD buffer does not support genlock, it is 
incompatible with video taping equipment. 


| 


CAD Buffer Color System 


| 


The CAD buffer supports the following map modes: 


:8-bit 

:Opaque-overlay 
:8-bit-and-foreground-overlay 
:8-bit-and-embedded-overlay 
:8-bit-with-overlay 
:8-bit-with-embedded-overlay 
:8-bit-with-foreground-overlay 


CAD Buffer Il Color System 


: The CAD buffer II color system is designed to replace the CAD buffer color 
i system. The CAD buffer II offers a 2-bit overlay. Pan is supported in 32-bit 
| increments; line-by-line scrolling is also supported. 


Resolution is programmable up to 1280 x 1024. The CAD buffer II can be run at 
NTSC and interlaced resolutions. 


f Digitizing Frame Grabber 


The digitizing frame grabber accepts incoming analog RGB video signals and 
converts this information to digital RGB data, which can then be stored in an 
image memory that is accessible from the CPU. A frame grab is done in one 
frame time (1/30 of a second). Once digitized, an image can be transferred to a 
| | color frame buffer for viewing, processed by the CPU in some manner, or 
“ani stored on the disk. 


The frame grabber works with NTSC (640 x 480) and PAL (640 x 575) 
| : resolutions. 
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Color Editor 

General Instructions 

Entering and Leaving the Color Editor 
Creating a Color Window from a Program 
Changing Defaults in a Color Editor Window 
Using the Color Palette 

Using the Color Editor 

Editing a Color 

Changing the Configuration 

Changing the Color Model Selection 


IMAN System 


Basic Concepts 

Simple Image Manipulation Functions 
Predefined Image Types 

Creating and Manipulating Images 
Transforming One Type of Image to Another 
Image Compression Techniques 
Sample Images 

Nondefault Image Types 

Image Scaling 

Primitive Scaling Functions 

IMAN Interface to Menus 

File Format 

Run-Length/Delta Encoding 
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Color Editor 


The color editor is a display-oriented, interactive program that allows you to 
custom-blend the color of your choice, using whatever color model is natural to 
your task. 


This chapter describes the functions you can call to invoke the color editor and 
explains the behavior and options available once it has been invoked. 


General Instructions 


To load the color editor, type the following at the command processor of any 
Lisp Listener: 


Load System Color-editor 


Since the intent of the color editor is to let you choose colors by seeing them, it 
is only reasonable to invoke the color editor on color screens. 


The color editor consists of two main programs. The color editor itself lets you 
blend and select one color at a time. An auxiliary program presents a palette of 
color chips and lets you do some simple manipulations to add the colors you 
want to the palette. 


The result of invoking the color editor is always a color object. Color objects 
are documented in Chapter 5—‘‘Color Objects.’ The essential contract of a 
color object is to remember the specification for a color. Do not confuse color 
objects with color ALUs, which are used to draw in color on a color screen. 


Entering and Leaving the Color Editor 


125 


The palette and color editor are pop-up displays; they disappear after you make 
your selection, without any disturbance to the color screen. 


The color editor is known to the color-demo system. You can invoke the color 


_ editor by calling (color:color-demo) and using [Edit Color]. This loads the 


color editor if it is not already loaded. 


If the color editor is loaded, you can invoke it from the System menu; [Color 
Editor] appears on the System menu’s programs column. 


Both ways of invoking the color editor are good for demos but useless for actual 
work because there is no way to get the value returned, which is the whole 
point. 

; The command processor commands Edit Color and Select Color can be used to 

! invoke the color editor and color palette, respectively. They are handy when 

you need to select a color and embed the resulting color specification in a 

program. 

From programs, the recommended entry points are the functions color:edit- 

“ color, which invokes the color editor, and color-palette:pop-up-color- 

| palette, which invokes the color palette. 


To leave the color editor or the color palette, use [Done], [Exit], or [Abort]. 


nS an, A ai oe eet 


: Creating a Color Editor Window from a Program 


: color-palette:pop-up-color-palette Function 
Fi &key initial-color short-life? screen 
f 

(force-zoom * force-zoom-default* ) 


‘ This function invokes the color palette and returns a color object or nil. 


i inttial-color If supplied, it should be a color object, 
which is the initial color in the palette’s 
selection box. 


short-life? If t, the first box you click on is selected 
and returned. In this mode, you cannot 
modify the palette, only select existing 
colors. 


screen If supplied, it should be a color screen. If 
omitted, an appropriate color screen is 
found or created. 


force-zoom If not nil, the screen is zoomed to make the 

palette fill a substantial part of the screen. 
Pit Otherwise the palette appears to be quite 
| small. 


color:edit-color &optional initial-color Function 
Invokes the color editor, using initial-color as the initial color in its selec- 
tion box. The first time the color editor is invoked, you have to use the 
mouse to specify the size and position of the color editor on the color 
screen. Subsequently, when a color editor is invoked, it appears at the same 
position. You can use [Edit Screen] on the System menu to change the size 
and position of a visible color editor. 
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Changing Defaults in a Color Editor Window 


The defaults are: 


:numeric-display? nil 

:edges-from :mouse 

:display-size .3 

:initial-color-space :ihs 
:initial-value-object-flavor ’standard-color 
borders 1 

:border-margin-width 0 

:Save-bits nil 


ee Example—Change the default color model from IHS to RGB. 


(defun make-my-color-editor-window ( ) 
(setq my-color-editor-window (tv:make-window ‘my-color-editor 
‘superior color:color-screen 
‘initial-color-space :rgb))) 


Using the Color Palette 


The color palette display is divided into four parts. 


The main part of the display is in the upper-right and consists of a page 
displaying 48 color chips, possibly including some empty positions marked 
with a dot. The pages are numbered, starting from 1; you can create as 
many pages of color chips as you want. 


Below the page display is a selection box that displays the color that is 
selected if you exit. The color in the selection box also has other uses, 
which are described in the section 
“Selection Box”’ of this chapter. 


Below the selection box are three 
function boxes, the most impor- 
tant of which is [Exit]. 


To the left of the page display are 
the page selectors, which show 
what page you are on and let you 
select other pages. 


Plate 10.1 Color palette 
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Page Display 
When you click left on any color chip in the page display, that color is copied 
into the selection box. 


When you click left on any empty color chip position, the color from the selec- 
tion box is copied into the chip. 


When you click right on any color chip, the position is emptied to make room 
for a new color. 


When you click middle on any color chip position, the whole row containing 
the chip is replaced with colors interpolated from the leftmost color to the 
rightmost color in the row. This is an easy way to get new colors into the 
palette. 
Selection Box 
The color visible in the selection box is used several ways. 

It is the color returned when you use [Done]. 

It is the initial color for the color editor when you use [Edit]. 

It is copied to any empty color chip on which you click left. 


It is copied from any nonempty color chip on which you click left. 


Function Keys 


The function keys have three options: 


[Done] Exits, returning the color in the selection box. 

[Edit] Calls the color editor to let you custom-blend a color. The color 
returned is put in the selection box. 

[Rows] Invokes a secondary menu of operations on rows of the page 
display. By using the rows display, you can make empty rows in 
the page display or regenerate the colors that were initially in 


page 1. 


Page Selectors 
The upper-left corner contains the current page number. 
The three green page selector boxes are marked as follows: 


1 Changes the page display to page 1. 
Changes to the next page. 
~ Changes to the previous page. 


When you click on any empty slot that could contain a color chip, the color 
from the selection box is copied into the chip. 
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P.6 
= Using the Color Editor 
When you first enter the color editor, you see a frame containing three types of 
BE panes. The topmost pane is called the color display pane. Under it are the com- 
ae ° 
mand pane and the slider pane. 
rr Color display pane 
Command pane 
rx 
kw 
Slider pane 
rt 
Plate 10.2 Color editor 
ri The color display pane displays the initial color when the color editor is 


entered. The initial color is the last color used. When you change the initial 

color or pass the color editor a color using the function edit-color, the color 

Pil display pane displays the current color. The current color is the color you are 
currently using. 


The command pane displays four menu items: 


7 
re [Done] Saves the current color (the color displayed in the top color 
ce display pane) and exits the color editor. | 
rt [Model] Displays a menu. (See the section “Changing the Color Model | 
Selection” in this chapter.) | 
rH [Config] Displays a menu. (See the section “Changing the Configuration” in | 
= this chapter.) 
ae: [Abort] Exits the color editor. If you were editing a color, the changes are 
| not saved. ‘1 
The slider pane displays one component of a color model. (See Chapter 5— 
= “Color Objects.) One set of three slider panes represents a color model. For 1 
— example, in the IHS color model the three slider panes represent intensity, hue, 
and saturation. | 
— Each slider pane contains a slider bar and a background color. The slider bar is 
si a thin vertical bar which, through its position, controls a component of the 
~ color model. The background color is the color behind the slider bar in the | 
i slider pane. 
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Editing a Color 


HARDWARE FEATURES 


AUXILIARY SYSTEMS 
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To edit a color, begin with the color model you want. The last color model used 
is displayed when the color editor is entered, so you usually do not need to 
make a new selection. If the color editor displays a color model other than the 
One you wish to work from, you should select a new one. (See the section 
“Changing the Color Model Selection” in this chapter.) 


The default color model is IHS. When you edit a color using this color model, 
you imitate the way an artist mixes paints on a palette. First, you choose a hue 
(color); you then lighten or darken the hue by mixing in white or black. How- 
ever, if the color model starts with white as the current color, you first need to 
increase the saturation to get a visible hue. If the color model starts with black 
as the current color, you need to increase the intensity and the saturation to get 
a visible hue. 


The mouse controls the color editing process. Use the mouse to change a com- 
ponent in a slider pane in one of two ways: continuous or incremental. The 
following paragraphs describe how to use the two editing processes to change 
the hue, the hue’s intensity, and the saturation. 


Continuous update is when you position the mouse over the slider bar in the 
hue slider pane and hold down the mouse button as you move the mouse left or 
right to change the hue. As you move the mouse, the hue changes in the back- 
ground of the display pane. How- 
ever, the background colors in the 
other slider panes do not change 
continuously because of the time it 
takes to redraw them. 


When you reach the desired hue, 
release the mouse button. The 
background colors in the other 
Plate 10.3 Color editor with low intensity slider panes and the current color 
in the top color display pane 
change to reflect the new color. 


Incremental update is when you 
position the mouse at the desired 
hue in the hue slider pane and click. 
The slider bar jumps to the new hue. 
The saturation, intensity, and cur- 
rent color in the top color display 
Plate 10.4 Color editor with pane also change to reflect the new 
increase in intensity 
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color. For example, if the background color in the hue slider pane changes from 
blue to red, the background color in the intensity slider pane changes to show 
what the new hue (red) looks like at all values of intensity. The background 
color in the intensity slider pane changes to black (low intensity) on the left and 
bright red (high intensity) on the right. 


The second step in editing a color might be to change the intensity to corre- 
spond to the new hue selection. High intensity is indicated in the slider pane to 
the right and low intensity is indicated to the left. For example, if the slider bar 
in the intensity slider pane is positioned all the way to the left, the current color 
has an intensity of zero. To increase the intensity, move the slider bar to the 
right, using the mouse continuously or incrementally. The intensity of the cur- 
rent color in the top display pane brightens. (See plates 10.3 and 10.4.) 


The third step is to change the saturation in the saturation slider pane, using the 
same procedure you followed to change the hue and intensity. 


You can change the color model components in the slider panes in any order 
and as often as you wish. For example, you can change the intensity and then 
the hue and saturation, or you can change just one component of the color 
model. 


Changing the Configuration 


To change the configuration, use [Config] in the command pane. A menu dis- 
play appears with five menu items. (See plate 10.5.) 


Display Size: Small Medium Large 
Specifies the size of the color display pane relative to the slider panes. 


Numeric Redisplay Mode: Continuous Incremental 
Specifies whether the numeric displays are updated continuously as the 
slider bar is moved, or incrementally after the mouse button is released. If 
the numeric display is turned off [No], this item has no effect. 


Numeric Display? Yes No 
Specifies whether or not the numeric values are displayed. (In plate 10.5, 
the numeric display is on [Yes].) Turning the numeric display off [No] dis- 
ables the numeric redisplay. Side labels on [Yes] disable the numeric display. 


Side abels7e svess= INO 
Specifies whether or not the slider pane labels are displayed on the side of 
the slider pane or on a separate line above the slider pane. (In plate 10.5, the 
side labels are off [No].) The default is on [Yes]. The side labels leave more 
room for the background color in the slider pane. Side labels on [Yes] dis- 
able numeric display. 


Changing the Configuration 
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Number of Color Segments: 20. 40. 60. 100. 
Specifies the number of segments in the background color from the left to 
the right of each slider pane. A segment is one of a series of color bars that 
make up the background color. If the number of segments is 100, the back- 
ground color is very smooth, prac- 
~ ¢ Small Medium Large tically continuous. If the number is 
: YesNo an 20, the background color has obvi- 
egnents: 20.40.60. 100. ous segments. The advantage of 
= meme | daving a small number of segments 
is that the background color up- 
dates much faster as you make 
changes. This menu item has an 
effect only on a direct color system. 
On a pseudo-color system, the 
number of segments in each slider 
pane color background is determined by the size of the color map and the 
number of slider panes, because there are only 256 colors to allocate. 


Plate 10.5 Configuration menu 


Color Mode: Use Standard Palette Use Best Use Color Map 
(Use Standard Palette] uses whatever color map is already available on the 
color screen. 


[Use Color Map] computes its own color map and temporarily forces the 
screen to use it. 


(Use Best] selects one of the above, depending on the type of screen. For 
direct color screens, it selects [Use Standard Palette] because an adequate 
selection of colors is normally available. [Use Standard Palette] on a direct 
color screen does not disturb the appearance of any other images that are 
simultaneously visible on the screen. For pseudo-color screens, [Use Best] 
selects [Use Color Map] to have an adequate selection of colors available. 
This causes any other images also visible on the screen to change color 
randomly while the color editor is in use. 


To select a menu item, position the mouse on the menu item option and click. 
The menu item is now highlighted, showing that you selected it. After you make 
your selection(s), use [Exit] to return to the color editor with the changes made. 


Changing the Color Model Selection 


To change the color model selection, use [Model] in the command pane. A 
menu display appears with four menu items. (See plate 10.6.) Each menu item 


132 10 + Color Editor 


ios 


fe 
re 64 


Ow 


rr 


wr 
ry 


bos ) 
eT roe §6UTT.”6hCOUrehC UW 


iol 


“ 


ia we wh 


) 
ye | 
7 


133 


specifies a different color model. To 
select a model, use [Yes] after the 
model selection. The new color 
model is now highlighted, showing 
that you selected it. If you select a 
new color model and want to turn 
off the previous model, you must 
use [No], or you will get two color 
models. 


Plate 10.6 Vodel menu 


If you select more than one color model, a set of three slider panes is displayed 
for each color model selected. (See plate 10.7.) For example, if you select both 
the IHS and RGB models, six slider panes are created (intensity, hue, saturation 
and red, green, blue). If you select 
all the color models, the color edi- 
tor fits in as many slider panes as it 
can. If the color editor runs out of 
room to fit all the slider panes, it 
removes the slider pane labels to try 
to make as much room as possible. 
After you make your selection(s), 
use [Exit] to return to the color 


Plate 10.7 Color editor using two i Hie aoe 
color models (IHS, RGB) editor with the changes made. 


The default color model is IHS, but you can change the default if you use a pro- 
gram to call the color editor. (See the section “Creating a Color Editor Window 
from a Program”’ at the beginning of this chapter.) You can also create a new 
color model. (See the section “Creating a New Color Model” in Chapter 5— 
“Color Objects.’”) 


Changing the Color Model Selection 
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IMAN System 


The Image Management (IMAN) system is a collection of utilities to load, store, 
and transform raster images. By using the IMAN system to manage raster images 
instead of creating your own image management system, you can: 


>» Prevent proliferation of incompatible formats for storing and exchanging 
images. 


> Use the basic techniques and the flavors that implement images as build- 
ing blocks for your applications. 


Basic Concepts 
By default, the IMAN system manages four types of images: 
1-bit-per-pixel 
8-bit-per-pixel 
24-bit-per-pixel 
32-bit-per-pixel 
All types of images have the following attributes: 


>» They are stored on disk either as simple raster arrays or as run-length/ 
delta-encoded arrays. The disk format is simple enough to be imple- 
mented on other file systems. 


> They reside in virtual memory either as skeletons, with the (large) raster 
arrays remaining on disk, or with literal bit-arrays already loaded. An 
image with bit-arrays displays rapidly but consumes a large amount of 
virtual memory. A skeleton image displays slowly but consumes a small 
amount of virtual memory. 


>» They can be created directly from windows, generated by programs, or 
loaded from disk. 
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> They can be viewed on any window with at least as many bits per pixel, 
with automatic expansion to larger formats when necessary. Several tech- 
niques have been implemented to compress images to fewer bits per 
pixel. (See the section “Image Compression Techniques” in this chapter.) 


The bit-arrays used by images are allocated from a resource, and the 
images themselves are kept track of. The net effect is that images are not, 
in general, garbage-collected. If you want to get rid of an image, you 
must explicitly kill it. 


Simple Image Manipulation Functions 


First, you must have loaded the system IMAGES. 


The simplest way to use IMAGES is to use the function save-window, which 
presents a menu that can be used to view existing images or create new ones. 
This function is used by the color demo menu item [Load or Save Image]. 


To preload images into virtual memory for later viewing, use the functions 
color:load-image-file and color:load-images. 


To locate images that have been loaded, use the functions color:find-image 
and color:find-images. 


To view an image on a window, use color:view-image or color:load-image- 
file-into-window. 


To save images that are newly created or that have been manipulated in memory, 
use color: write-image. = 


— 


To get rid of an image you are finished with, use color:kill-image. 


To perform more complex operations on images, you need to load them, locate 
them, and then send the images the appropriate messages to accomplish what 
you want. : 


color:find-image optional image-name Function 
Searches among the loaded images for those matching the specified image 
name. Wildcard components are accepted. If more than one image matches, 
a choice menu is displayed for you to make a selection. 


color:find-images &optional image-name Function 
Similar to find-image, except that it returns a list of all the names of loaded 
images that match the specified image name. Wildcard components are 
accepted. If more than one image matches, a choice menu is displayed for 
you to make a selection. 
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color:kill-image image &key (remove-from-database t) Function 
(discard-bit-arrays t) — 
— (kill-derived-images t) 
= Makes this image garbage-collectable. If remove-from-database is t, re- 


moves this image from the list of known images, so it will not be found 
again by find-image. If discard-bit-arrays is t, returns any bit-arrays to the 
resource so they can be reused. If kill-derived-images is t, recursively kills 
any images that were generated automatically from this image. 


7 color:load-image-file file &optional (binary-too t) Function 
a Loads the image file. If binary-too is t, the binary for the image’s binary data 
is loaded into an array in memory. Otherwise, it remains on the disk and is 


i loaded on demand. Loading an image with binary-too nil is the proper way 
to get everything about the image except its bit-arrays. 

= color:load-image-file-into-window /ile window &rest options Function 

— Loads an image directly from a file to a window. The options are passed on 
to the function view-image. 

TT color:load-images pathname &optional (binary-too t) Function 


&key (menu t) (load t) label 

Scans pathname for image files with matching names. pathname defaults to 
re the value of *image-directory*. binary-too determines whether the bit- 
Pex arrays are loaded or left on disk. If menu is t, load-images displays a 

multiple-choice menu of matching images and lets you select a subset to be 
tT. loaded. If /oad is t, the images are actually loaded and a list of images is 
ee a returned; otherwise, a list of pathnames is returned. /abel is the label that 

appears at the top of the menu. 


color:save-window window &rest keywords Function | 
Displays a choose-variable-values window to let you specify an operation to 
nae load or save an image to or from an arbitrary window. window is a window 
— Or a raster array. 
The keywords can be: 
rv :edges Specifies the edges to use for loading or sav- 
ee 


ing from the window. Edges can be :inside 
to save the normal inside area of the win- 
vn dow, :everything to save the window and 
its borders, :mouse to let you specify a rec- 
tangle using the mouse, or a list of four inte- 
ail gers that specifies the left, top, right, and 
Bip bottom edges. 


Ta 
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:file 


:menu-icons 


:rle 


. 


:ask 


:print 
:Clear-before-load 


:where 


}! :load-or-save 


:color-map 


oe ol 


ae 


i | :properties 


ee 
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Specifies the name of the file or image to 
use. The name is wildcard-matched against 
the possible sources, and a submenu is pre- 
sented to force you’to select one image 
name to be used. 


Default is *default-use-image-icons* 


(which is initially t). If t, menus that contain 


images to choose from contain tiny pictures 
of the image if the image is readily available. 


Marks the image for run-length /delta en- 
coding when it is written. 


Uses the menu. If nil, the supplied values 
and defaults are used to do the operation, 
without menu confirmation. 


Prints statistics on how efficient run-length / 
delta encoding is. 


Clears the window before loading anything 
into it. 


Specifies where the image comes from. Can 
be :file to specify a file or :image to spec- 
ify an image that has already been loaded. 


Specifies whether the operation is to load or 
save the image; the value of this can be 
:load, :save, or nil, in which case a menu 
prompts you to specify the actual value. 


If supplied, this should be an instance of 
type color:standard-color-map, which is 
used as the color map associated with the 
image created, if it uses one. 


Initial property list of the image. Properties 
of the image are saved if their names are 
mentioned on color:*interesting- 
properties* or if they are contained in an 
:interesting-properties property of the 
image. 


uid 


F 
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color:view-image window &optional image-name Function 
&rest keywords 
view-image is the principal function to copy an image to a window. Using 
the optional keywords, it is possible to transfer an arbitrary part of an image 
to an arbitrary place in a window. 


window can be any window. image-name can be any specifier for the func- 
tion find-image. 


The keywords can be: 


:function The message name to be sent to the image, 
with the rest of the keyword arguments. 
— ae The default is :send-image-to-window. 
:Clear-before-load Does a :clear-window before the image is 
loaded. 


i 

eae :edges Selects where the image is displayed on the 
window. Edges can be :inside to load to 

7 the upper left of the window’s inside, or 


ee s:mouse to specify a list of edges from the 
mouse in the usual left, top, right, bottom 
format. The default is :inside. 


:wdx The x coordinate of the window at which 
to load the image. 


= 
— >wdy The y coordinate of the window at which 
to load the image. 
D1 :dx The x coordinate of the image from which 
ry to start loading. | 
= | | :dy The y coordinate of the image from which. 
— to start loading. | 
Sees sheight The maximum height of the image to dis- 
ra play. 
:width The maximum width of the image to dis- 

vom ; play. . 

wi _ sedges, :wdx, :wdy, :dx, :dy, :width, and :height interact with one 
Be another as well as with the sizes of the image and the window. Conflicts in 
i size or edges are resolved by taking the largest rectangle that meets all the 


constraints. 
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color: write-image filename image &optional format Function 
Writes the specified image to the specified file in the specified format. file- 
name is the name of a file in which to save the image. image can be an 
image or an image name. format can be :fasd (meaning FASD format) or 
anything else (standard .dump format). , 


Predefined Image Types 


Images are composed of flavor instances, which are constructed of modular 
components in the usual mixin style. This section describes the instantiable 
flavors for each type of image. The image types and their attributes follow. 


11 


> 1-bit-per-pixel images: 
Use the basic flavor color:b&w-image. 
Do not use a color map. 
Store the raster as an art-1b array. 


Are displayed directly on the black-and-white screen or are expanded to 
a black-and-white representation on color screens. 


>» 8-bit-per-pixel images: 


Use the basic flavor color:false-color-image. 


Use an optional color map, which is normally an instance of flavor 
color:standard-color-map. Images with no color maps are displayed 
using whatever map is current. Images with a color map are normally 
displayed using the color map. 


Store the raster as an art-8b array. 


Are displayed directly on 8-bit screens, after the screen’s color map is set 
appropriately. On direct color screens, a translation array is constructed 
to expand the image to 24 bits. To view on a black-and-white screen, 
several techniques are available to represent an 8-bit picture using 1 bit 
per pixel. 


» 24-bit-per-pixel images: 


Use the basic flavor color:rgb-image. 
Do not use a color map. 
Store the raster as three art-8b arrays, one each for red, green, and blue. 


Are displayed directly on direct color screens. On 8-bit screens, you can 
view one color at a time or use one of several techniques to compress the 
image to 8 bits per pixel. To view on a black-and-white screen, several 
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techniques are available to represent the picture using only 1 bit per 
pixel. (See the section “Image Compression Techniques” in this chapter.) 


> 32-bit-per-pixel images: 
Use the basic flavor color:32b-image. 
Do not use a color map. 
Store the raster as a single, art-fixnum array. 


Are similar to RGB-IMAGEs. Thiry-two-bit images are slower to work 
with because they impose larger paging loads. 


Creating and Manipulating Images 


There are two basic ways to create an image. One is to initialize it from a win- 
dow; the other is to create it from scratch. This section tells you how to create 
images from scratch. 


The basic function to create an empty image is color:make-image, which 
accepts many init options that can be used to initialize the image. To be useful, 
all images must have a width, a height, and one or more bit-arrays, which have 
to be filled with data. They can also have a mame, an associated file, a color 
map, and miscellaneous other properties. 


Messages such as :width, :height, :name, :source-file, :property-list, and 
:get return basic descriptive information about images; there are corresponding 
:Set-xx messages and init options. 


The :create-bit-arrays message allocates bit-arrays of the desired size, and the 
:discard-bit-arrays message discards them. 


The :take-image-from-window message creates appropriate bit-arrays and 
copies bits from a window. The :send-image-to-window message copies the 
image to a window for viewing. :load-image-file forces an image whose bits 
reside on disk to load an image, either to a window or to keep permanently. 


The :write-files message writes a permanent copy of the image to a disk file. 


In addition to these basic messages, a group of transformation messages trans- 
forms one image type to another, and a group of scaling messages creates en- 
larged or reduced images. These message groups are described in the following 
sections. 


:create-bit-arrays : Message 
Causes the image to allocate bit-arrays corresponding to its current width 
and height. The actual size of the arrays is not necessarily the same as the 
size specified by width and height; it might be larger. 
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:data-array Message 
For images other than type RGB-IMAGE, returns the data array for the 
image, or nil. RGB-IMAGEs do not accept this message (use the :rgb mes- 
Sage). _, & 


:Set-data-array new-array Message 
For images other than type RGB-IMAGE, sets a new data array and discards 
the old. RGB-IMAGEs do not accept this message (use the :set-rgb mes- 
Sage). 


:discard-bit-arrays Message 
Returns the bit-arrays (if any) to the bit-arrays resource. It is not harmful if 
the arrays were not originally allocated from the resource. 


:full-color-p Message 
Returns t if this image is nominally a direct color image, which at present 
means RGB-IMAGE or 32B-IMAGE. 


:get Droperty-name Message 
Returns the specified property of the image. See also :putprop. 
:height Message 


Returns the specified height of the image, which is not necessarily related to 
the height of any bit-arrays currently in use. 


sheight Init Option 

:set-height new-height Message 
Sets the intended height of the image. This does not affect the current bit- 
arrays in any way. 


:inside-size Message 
Returns two values, the width and height associated with the image. 


:load-image-file &key force-reload Message 
Causes an image to load its bit-arrays, if they are not already loaded. If force- 
reload is t, the bit-arrays are loaded even if they are believed to be already 
loaded. 


color:make-image flavor &rest init-options Function 
make-image is the basic function that creates an image. It accepts the type 
of image to be created and other initializations for the newly created image. 
flavor can be any flavor but is presumably a flavor based on one of the 
above types of image. The following init options are accepted by all images: 
sheight, :name, :property-list, :setup-color-map, :source-file, 
:width. In addition to the above, all the basic image types except RGB- 
IMAGE accept :data-array as an init option. RGB-IMAGEs accept any or all 
of :red, :green, and :blue as initializations for their data arrays. 
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:name Message 
Returns the name associated with the image. Usually, but not necessarily, 
this is a symbol and is the same as the name of the file associated with the 
image. 


:name Init Option 

:Set-name new-name Message 
Sets the name associated with the image, which also acts as the default for 
the filename associated with the image. 


:property-list Message 
Returns the whole property list associated with the image. This property list 
can contain items generated automatically by IMAN; it can also contain any 
properties you explicitly specified. Not all properties are automatically 
saved with an image. The saved properties are those whose names are on 
the global list color:*interesting-properties*, plus those properties 
whose names are on the image’s own :interesting-properties property. 


:putprop new-value key Message 
Puts new-value on the image’s property list, associated with key key. 


sremprop key Message 
Removes any property with name key from the image’s property list. 


:rgb Message 
For images of type RGB-IMAGE only, returns three values: the red, green 
and blue arrays associated with the image. Messages :red, :green, and 
:blue also exist. 


:Set-red Message 

:Set-green Message 

:Set-blue Message 
For images of type RGB-IMAGE only, sets the red, green, or blue array 
associated with the image. 


:send-image-to-window window &key (dx 0) (dy 0) Message 
(wdx 0) (wdy 0) (width width) (height 
height) (edges :inside) force-reload 
clear-before-load compression-method 
This is the lower-level function called by view-image after it has deter- 
mined the image to be viewed. All keywords are the same as for view- 
- image. 


:Size Message 
Returns two values, the width and height associated with the image. 
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:take-image-from-window window &key edges displaced Message 

(wdx 0) (wdy O) (dx O) (dy 0) 

(new-bit-arrays t) color-map width height 
This is the basic method used to copy bits into an image. window can be 
either a window or a raster array. If displaced is t, the image creates bit- 
arrays that are conformally displaced into window, so no new storage is 
allocated. This is used mainly when the image is only to be used to save 
window's bits to the disk. If ew-bit-arrays is t, entirely new bit-arrays are 
allocated, otherwise the transfer overlays whatever bits were already part of 
the image. If new-bit-arrays is nil, the remaining keywords should not 
imply increasing the size of the image. If color-map is supplied, it is used to 
initialize the setup-color-map variable of the image if it has one, and it 
should be an instance of color:standard-color-map. If no color map is 
supplied, and the image normally requires one (that is, if it is a pseudo-color 
image), One is created from the current color map associated with window. 
Wdx, wdy, dx, dy, width, height, and edges have the same meaning as for 
the function view-image. 


:width Message 


Returns the width of the image, which might not be the same as the width 
of the bit-arrays. 


:width Init Option 
:Set-width Message 


Sets the width of the image. This has no immediate effect on the bit-arrays 
of the image. 


:Setup-color-map | Message 


Returns the color map specification associated with this image. Only images 
of type color:false-color-image will have a color map. 


:setup-color-map Init Option 
:Set-setup-color-map map Message 


Sets the color map associated with the image. This should be an instance of 
type color:standard-color-map or nil. There are several “standard”’ 
color maps which, if you use them, result in smaller .image files. They are: 


color: * standard-b&w-map* 
A ramp of gray tones. 


color: * standard-false-color-map * 
The standard 6x6x6 pseudo-color map that 
is used by 8-bit color systems. 
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vat color: * primary-false-color-map* 

The 8x8x2 pseudo-color map used by the 
frame grabber when grabbing in pseudo- 
rine color mode. he 


color: * primary-only-color-map* 
—— A pseudo-color map consisting only of the 
eight primary and secondary colors. 


:write-files &optional file &key (print t) (rile :unk) Message 
Writes out the binary and text files associated with the image. If file is 
supplied, it becomes the file associated with the image. If print is t and rle 
is t, a message is printed describing the effectiveness of run-length /delta- 


rp encoding the image. If rle is t, the binary file is run-length /delta-encoded, 
a which usually results in a considerably smaller file. 
OD. ee Example—Implement a function key to save the main screen as an 
- image on the FEP file system. 
(defun save-main-screen-as-image (&optional (arg nil)) 
ae (let ((image (color:make-image ’color:b&w-image :name “main screen” 
‘properties | 
= ‘(comment “image from main screen” | 
Pri ‘interesting-properties '(:system) | 


‘system ,(si:get-system-version)) 
‘rle t 
Piet ))) 
(send image :take-image-from-window 
tv:main-screen 
PEt ‘edges (if (null arg) :inside :mouse)) 
(send image :write-files “fep: >” :print nil) 
(color:kill-image image) 
un ) 


(tv:add-function-key # | ’save-main-screen-as-image 


sini “Save the main screen as an image on the fep file system 
— 1 Use the mouse to designate a rectangle.”) 

a Transforming One Type of Image to Another 

\ ie 


All image types can be transformed to images of other types. If the transforma- 

tion can preserve all information, it does. Essentially, this means that transforma- 
itt tions to equal or greater bits per pixel yield the same image in the new format, 
but transformations to smaller numbers of bits per pixel necessarily lose infor- | 
mation (see the following section “Image Compression Techniques’’). | 
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All images accept the following transformation messages, which create reformat- 
ted copies of the original image. All the transformation messages accept key- 
word arguments :file and :name, plus additional keyword arguments 
appropriate to the transformation. 


4 
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The transformation messages are :create-1b-image, :create-8b-image, 
:create-rgb-image, and :create-32b-image. All four messages are accepted 
by all kinds of images, and all accept the following keyword arguments in addi- 
tion to other arguments appropriate to the type of transformation. 


ia 


:file The name of the file with which this image is to be associated. 
:name The name of the image. If no name is supplied, a descriptive name 
is created, based on the old name and the transformation. 


' 
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:create-1b-image &keywords (of color:rgb-image Message 
and color:false-color-image) 


Uses dithering to generate a 1-bit-per-pixel representation of an image, 
which can be either an 8- or 24-bit-per-pixel image. 


" 


J 


The keywords can be: 


‘ 


NM :brightness 77 Specifies a value to tweak the brightness. 

i The basic algorithm tweaks :brightness 
until the total exceeds :threshold, then 
subtracts :brightness and the process con- 
tinues. The default is 1.0. 


J 


| :threshold 77 Specifies a threshold value for :brightness. 
| The default is 1.0. 


r 


You can tweak :threshold and :bright- 
ness to generate a pleasing image, but the 
i default values are a good starting point. 


r 


:Create-8b-image &keywords (of color:rgb-image) Message 
Creates an 8-bit representation of a 24-bit image. 


The keywords can be: 


} :>window Specifies a window in which to replay the 
new image. Can be an 8-bit-per-pixel win- 
Hi dow or array. If it is not supplied, only the 
| new image is created. 


jitter Determines the amount of jittering to use. 
hi Valid values range from 0 to 1.0. The effect 
depends on a complex interaction of jitter 
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 & 
we and other parameters. nil means no jitter- 
ing. t means choose a reasonable default. 


ing is highly recommended for the :palette 
compression method, with or without :jit- 


1a ter. For the :peano compression method, 
ue :dither should be used only with :jitter. 
:method :palette to use the standard palette to 


create an 8-bit image. This is faster than 
:peano, but less satisfactory. When used 
with :jitter and :dither, it can be quite 
ivi close to :peano in quality. 


speano to use the peano-mapping tech- 
ae nique. This usually results in a very high 
We; quality image, but can fail to satisfy for path- 
ological images. Careful use of :jitter and 
a :dither can improve the result, but careless 
nei use can result in serious reproduction arti- 
facts. 


:red, :green, or :blue to generate a black- 
vee and-white image using only one of the 
image plans. 


:primary-palette to create a dithered 8-bit 
pixel image using only the eight primary 
unit and secondary colors of the standard 8-bit 


ps :grayscale to create a black-and-white | 
image with the intensity of the gray pixels | 

corresponding to the IHS intensity of the | | 
ni original. | | 
sd | 


a :dither t or nil, to indicate dithering or not. Dither- 
te 


wrist palette. This is a hack that converts direct 
color images so they can be printed on a 
‘nl D-SCAN printer. 
\ (bor 
:bins-per-color 7 Specifies how many bins are in the sample 
: space for each color. The default is 64, 
rip : : : 
nn which is a reasonable value to start with. 
:buckets 77 Specifies how many colors the color map 
oT eventually comes up with. The default is 
sabi 254, which is a reasonable value to start 
with. | 
on | 
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:create-rgb-image Message 
Creates an RGB-IMAGE from some other image type. Since this is always an 
information-preserving transformation, no additional arguments are 
needed. 


:create-3 2b-image Message 
) Creates a 32B-IMAGE from some other image type. Since this is always an 
information-preserving transformation, no additional arguments are 
needed. 


Ei 


image Compression Techniques 


| The image compression techniques described in this section represent an image 
— using fewer bits per pixel than the original image uses. These techniques should _ 
not be confused with run-length/delta encoding. Run-length/delta encoding is 
exact and does not change the image. These image compression techniques are 
ij independent of, but can be used in conjunction with, run-length/delta 
| encoding. 


i 


{ 


4 All image compression techniques cause reproduction errors. Small errors are 
i usually not noticeable (which is the intended effect), but for some images and 
| techniques, gross, unexpected, and undesirable errors in reproduction occur. 

Such errors are called artifacts. 


| After you compress an image you should always inspect it for artifacts. You 
HH should make sure that you are satisfied with the result before you discard the 
| original. 


Hl The two principal techniques used to reduce visual artifacts in compressed 
images are called dithering and peano-mapping. These techniques permit use 

| of heuristics that can modify (or degrade) the original image. For example, to 
compress an image from 24 bits per pixel to 8 bits per pixel, an image compres- 
sion technique “throws away” information in the original image. The goal is to 
throw away the information that is redundant and unnecessary in the original 
and reprocess the information in the new image to reduce the perceivable arti- 

i facts of the compression as much as possible. 
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| 

| Dithering is one of the principal techniques used to compress images. If you 

i have an image that requires colors that are not included in the palette you are 
using, dithering continuously tracks the “error” in the colors you have chosen 
and always chooses colors from the palette based on the desired color plus the 

| current error. Dithering matches the average color of the picture to the desired 

color. The “error” term is dealt with in many ways, and the cumulative error is 

defined in many ways. 


Ah 
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One of the principal advantages of dithering is that a common palette can be 
used to represent many images, so they can all be displayed simultaneously. 


Dithering keeps the error terms separately for red, green, and blue. RGB is the 
easiest color model to use, and the results are generally satisfactory, but the 
error terms could be kept by any other color model. Each model gives slightly 
different results. 


Dithering limits the absolute error to one-half the dynamic range, so the total 
error can never be more than + 128. Dithering also causes the error to decay by 
a factor of 0.75 after each pixel, so that the errors tend to ‘““damp out” rather 
than continue accumulating to the clipping boundary. Both of these techniques 
reduce the number and seriousness of artifacts caused by dithering. Finally, the 
error is reset to zero at the beginning of each scanline, since the left and right 
sides of the image are not generally related. 


Jittering is similar to dithering, except instead of an actual “error”’ a random 
“error” is added. This tends to break up contour lines, which are usually created 
during image compression. The amount of jitter that gives the optimum result 
varies. When you request jittering but do not specify the magnitude, the 
jittering default is about one-half the value of the low-order bit. 


Peano-mapping creates a custom color map for each image, and is the default. 
The color map is optimized for that particular picture. The peano-mapping 
algorithm is based on a mathematical entity called a 3D peano-curve. 


Peano-curves have two properties that make them useful for image 
compression. First, they are space filling, meaning that a 3D peano-curve visits 
every point in a volume of space exactly once. Second, peano-curves have 
considerable /ocality, meaning points that are nearby in the original space also 
tend to be close together on the (linear) peano-curve. 


Peano-mapping generates a custom color map as follows: 


First, it takes a histogram of the colors used by the image. This RGB histo- 
gram is regarded as a 3D “volume” and uses a peano-curve to walk through 
the volume, accumulating the total number of histogram samples 
encountered. 


Assuming the color map is going to be 7 colors, the peano-curve is divided 

into m segments, each of which is represented by a single color in the final 

color map. The locality property of the peano-curve ensures that adjacent 
- samples are similar colors. 


Next, the centroid of each segment is taken to choose the color to represent 
the segment. Finally, a quick sort finds and moves any points that are too far 
from their centerpoint (and closer to some other centerpoint). The color 
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map of histogrammed colors to a small number of color map colors gener- 
ates the final image. 


Peano-mapping takes advantage of the fact that the colors in a “‘real image” tend 
to form clusters in color space. Because of this, it is possible to vastly reduce the 
number of distinct colors required to make an acceptable image. 


Sample Images 


A series of sample images are included with the color system to illustrate two 
different compression techniques: peano-mapping and palette. The images can 
be found under the wildcard pathname images:8bit;springday*. 


The sample images are derived from the full color painting Springday. Springday 
was painted using S-Paint on a 24-bit-per-pixel system. Computer-generated 
images tend to be more difficult to convert to 8 bits than images captured by the 
digitizing frame grabber, because they usually contain very regular structures 
that cause aliasing artifacts when the image is processed. Images captured by the 
digitizing frame grabber are less demanding because they contain random varia- 
tion that masks artifacts. 


The following reductions to 8 bits are demonstrated in the sample images: 
Springday-peano 


This rendition uses peano- 
mapping. You can see a slight 
horizontal banding effect in 
the blue sky background, 
especially in the center left, 
but otherwise it is quite 

true to the original. (See 
plates! | ste) 


Springday-peano-d 


This rendition uses peano- 

Plate 11.1 Peano-mapping compression mapping and also includes 
technique dithering. It is markedly infe- 

rior to the previous image and shows the typical artifacts that occur when you 

combine dithering with peano-mapping. Note the odd spots of color on the 

shading of the hills, the severe horizontal stripe connecting the two stalks in the 

upper-center of the image, and the streaking of the fine grass at the bottom. 
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The principal cause of the artifacts is that dithering tends to move the ‘‘desired 

color” into zones that were not represented, or poorly represented, in the origi- | 
nal histogram. Such zones tend to be assigned to inappropriate colors, since | | 
there is no “mass” associated with the color to force it to bé associated with a | 
closely approximating color. : 


Springday-d-06, Springday-d-13, Springday-d-25, Springday-d-100 


These four renditions use peano, dithering, and jittering with the jitter parame- 
ter at 0.06, 0.13, 0.25, and 1.00, respectively. 


-06 is slightly different from Springday-peano-d but not noticeably better. 


-13 is quite a bit better and is perhaps the best rendition of all. The horizontal 
banding from Springday-peano is not present, and the streaking and other arti- 
facts from the dithered images are not present. There is a very slight “tail’’ ex- 
tending to the right of the bottom-leftmost pair of clouds, and the yellow color 
in the center of the lower-rightmost blossom has been shifted noticeably toward 
green. 


-25 has a little too much jitter. The striping and banding are not present, but the 
clouds look a little grainy and there is some salt-and-pepper noise in the hill 
shading. 


-100 also has too much jitter. The jitter is manifest mostly in a noticeable check- | 
erboard effect in the blue sky background. 


Peano Compression Summary 


Using peano-mapping alone is often sufficient. When combined carefully with 
dither and jitter, the effect can be improved, especially for difficult images that 
use many colors. 


Springday-palette 


This rendition uses only the stand- 
ard palette of 256 colors to repre- 
sent the image. It is extremely 
contoured, especially in the color 
gradient backgrounds of the sky 
and the pond. Some details are 
almost totally lost, such as the hill 
shading. (See plate 11.2.) 


Springday-palette-d 
This rendition adds dithering. The 


result shows considerable improve- 
Plate 11.2 Palette compression technique 
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ment, but it is still markedly inferior to Springday-peano and Springday-peano- 
d-13. Note the vertical banding in parts of the sky (especially between the 
stalks), which is caused by the regular dithering correction. 


Springday-palette-d-50 


This rendition adds a small amount of jittering. A small amount is actually large 
compared to the jittering used in peano-mapping. In peano-mapping, the abso- 
lute distance between colors is small, so a very small amount of jittering can 
change the color. In palette compression, the absolute step between colors is 
quite large, so the jittering is more intense. 


The effect is slightly different but not significantly better. For example, note the 
slight improvement in the rendering of the sky near the water line. 


Springday-palette-d-100 


This rendition uses palette compression and is the best sample of this tech- 
nique. There is still some salt-and-pepper noise and vertical and horizontal 
banding. 


Springday-palette-d-200 


This rendition uses too much jitter. There is very noticeable salt-and-pepper 
noise and more severe banding than in the previous image. 


Palette Compression Summary 


If you use palette compression alone, the result is hardly ever satisfactory. If you 
combine palette compression carefully with dither and jitter, you can get a bet- 
ter result. Even so, it will not look as good as an image compressed with peano- 
mapping. 


Nondefault Image Types 


The four default image types are not intended to be the only image types. You 
can augment these four default image types to store additional information with 
an image. 


All images respond to three messages, which control the process. These mes- 
sages are :image-dump-form, :binary-dump-form, and :create-init-plist. 
These messages are combined using :nconc method combination, so each 
mixin adds its own piece to the complete form. See the document Reference 
Guide to Symbolics-Lisp for a description of the :nconc method combination. 
To augment the default image types, add these three messages to your mixin to 
store whatever additional information you need with the image. 
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vl :image-dump-form Message 
“2 Prints the result in the .image file. Each mixin contributes an appropriate 
ja list, in property list format, which becomes part of the make-image form. 
= For example: 


X=>#<image APPLE> 
(send * :image-dump-form) => 
(:rle ‘(rle-array-2 rld-array-2) 


366 


‘name ‘“apple” 


— ‘properties ‘(:date “2//06//86 14:14:51” 
or author ‘““ddyer’’) 
:width 640 :height 484) 
—- Here is one of the mixin components that contributes to the result: 
<o (defmethod (essential-image :nconc :image-dump-form) (_ ) 
mm ‘(:width ,width :height ,height)) 


Items of interest stored on the image’s property list are dumped automati- 
tl cally if the property names are on the list *interesting-properties*, or if 
they are contained on the image’s :interesting-properties property. The 
current default value of *interesting-properties”* is: 


— '‘(:artist :author :credits :comment :creation-parameters 
‘copyright :date :owner :title :interesting-properties) 
—- a 
— ee WARNING: The items returned by :image-dump-form should not contain any arrays, in- 
stances, or other objects that cannot be printed readably. The form is written into a text file 
Tt (using print) and must be readable using read. 
@ :binary-dump-forms Message 
This is constructed exactly as :image-dump-form, except that its contents 
mn are used to specify the .dump file. Binary dump forms should consist 
ae strictly of alternating keywords and arrays. The keywords should corre- 
spond to settable instance variables of the image flavor. The arrays should 
Tk be 1D or 2D arrays that contain only integers. For example: 
X => #<image APPLE > 
UE (send * :binary-dump-form) => 
oa (:rle rle-array-2 :rld rid-array-2 
red #< art-8b-640-484 67702226 > :green 
rE #< art-8b-640-484 115240000 > :blue #<art-8b-640-484 115467206 >) 
ie 


los Nondefault Image Types 


One of the mixin methods that contributes to the result is: 


(defmethod (rgb-image-mixin :nconc :binary-dump-form) (_ ) 
‘cred ,red :green ,green :blue ,blue)) 


For rgb-image-mixin, :red and :set-red are messages. :red is an init 
keyword as are :green and :blue. 


:create-init-plist Message 
This message is not normally used by images. It permits you to save images 
in an ordinary FASD format (regular binary files). Normally, the value of 
:create-init-plist should contain the contents of both the other two lists, 
but everything in them must be dumpable in FASD format, the format of 
3600-family machine BIN files. For example: 


X => #<image APPLE > 


(send * :create-init-plist) => 
(rle '(rle-array-2 rld-array-2) 
red '#<art-8b-640-484 67702226 > 
:green '#<art-8b-640-484 115240000 > 
‘blue '#< art-8b-640-484 115467206 > 
‘name “apple” 
‘properties ‘(:date “2//06//86 14:14:51” :author “ddyer’’) 


-width 640 :height 484) 


Image Scaling 


Images can be scaled arbitrarily in size, independently in x and y. There are two 
basic methods: 


The “fast-but-inaccurate,’ which works by simple pixel replication (or 
selection). 


The “slow-but-accurate,’ which antialiases by proportionally averaging 
all the source pixels that contribute to each destination pixel. 


Images also respond to the messages used by menus, which makes it possible to 
construct menus that contain “tiny” renditions of images. 


:create-scaled-image &key scale-factor scale-function fast Message 
This is the “simple” user interface to create a scaled version of an existing 
image. scale-factor should be a number indicating the expansion factor for 
the image. For example, scale 0.333 creates a new image one-third the size 
of the original. fast should be t or nil. If t, the scaled image is created using 
pixel selection; if nil, the scaled image is created using pixel averaging. 
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:transfer-scaled-image (o-image &key fast from-left from-top Message 
to-left to-top from-right from-bottom 
to-right to-bottom 
This message actually creates and transfers a scaled image from part of 
“this” image to part of some other image. The from-xx coordinates desig- 
nate a rectangle in the source image, and the fo-xx coordinates designate a 
rectangle in the destination image. The contents of the source rectangle, 
appropriately rescaled, are transferred to the destination rectangle. 


Primitive Scaling Functions 


These underlying functions are used to create the scaled images. They operate 
on bit-arrays, rather than images. Examples of these functions can be found in 
the mouse-pan-zoom-window option of color:demo. 


zoom-rectangle &key (composition-function #’ average-pixels) Function 
from-array (from-left 0) (from-top 0) 
(from-right (array-dimension-n 1 from-array)) 
(from-bottom (array-dimension-n 2 from-array)) 
to-array (to-left 0) (to-top 0) 
(to-right (array-dimension-n 1 to-array)) 
(to-bottom (array-dimension-n 2 to-array)) 
translation-array 


This is the workhorse function that controls all scaling. The basic algorithm 
is to call the composition function to generate the value for each destination 
pixel. 


from-array and to-array should be 2D arrays. 


All the from-xx and to-xx coordinates should be fixnums within the bounds 
of the arrays. 


composition-function should be chosen to produce the resulting pixel cor- 
responding to a rectangle in the from-array. The following composition- 
functions exist: 


Primitive Scaling Functions 


Name 
AVERAGE-PIXELS 
AVERAGE-RGB-PIXELS 


AV ERAGE-FALSE-COLOR- 
PIXELS 


AVERAGE-COLOR-MAP- 
PIXEES 


AVERAGE-PIXEL-TO- 
PAB ae 


CENTER-PIXEL 
CENTER-RGB-PIXEL 


CENTER-FALSE-COLOR- 
PEXSEE 


CENTER-COLOR-MAP- 
rlbs@ ab 


CENTER-PIXEL-TO- 
PAGER 


Antialias 
Yes 
Yes 
Yes 


Yes 


Source 
Array Type 


art-8b, grayscale 


art-fixnum, RGB 


art-8b, standard 
palette 

art-8b, any 
palette (trans- 
lation array), 
art-fixnum (no 
translation) 

List of R,G,B 
arrays 


art-8b, grayscale 
art-fixnum, RGB 


art-8b, palette 


art-8b, any 
palette (trans- 
lation array), 
art-fixnum (no 
translation) 


List of R,G,B 
arrays 


Destination 
Array Type 


art-8b, grayscale 
art-fixnum, RGB 


art-8b, standard 
palette 


art-8b, standard 
palette 


art-8b, standard 
palette 


art-8b, grayscale 
art-fixnum, RGB 


art-8b, palette 


art-8b, standard 
palette 


art-8b, standard 
palette 


translation-array is required by some composition functions to translate 
1- or 8-bit pixels into some corresponding 24-bit pixels. 


IMAN Interface to Menus 


All image-viewing functions that potentially present a menu of images accept 
:menu-icons as a keyword argument. The default is the value of 

color: * default-use-image-icons* , which is initially t. If :menu-icons is t, 
the menu items appear as tiny renditions of the image if possible, rather than 
just the image name. The image name still appears in the mouse documentation 
line. 


The following messages implement the menu protocols that permit an image to 
appear in a menu. 
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:menu-bounding-box-size Message 
The bounding box size is determined as follows: 


If the image has a :menu-scale property, it is used as the desired scale 
factor to use on this image in menus. Otherwise, *default-image-menu- 
size* (which defaults to 64.) is the larger dimension, and the shorter di- 
mension is computed to keep the same aspect ratio as the original image. 


:menu-print Message 
The image calls its :find-scaled-image method to get the image to display. 


:find-scaled-image scale-factor Message 
This message rounds the scale factor to the nearest percent and inspects its 
:scaled-images property for an image with that size. If none is found, it 
creates one with FAST-P T and caches it. 


File Format 


Each stored image is contained in two files: 


A text file that contains type, size parameters, color maps, and comments. 
For an image named “Foo,” the text file is normally named “Foo.image.” 


A binary file that contains the bit-arrays. For an image named ‘“‘Foo,’ the 
binary file is normally named “‘Foo.dump.” 


Storing an image in two files provides several advantages. A text file makes it 
convenient for you to read and comment images. The binary file and the text 
file can be loaded separately, making it possible to view images without using a 
large amount of virtual memory. The binary file can also be loaded directly from 
a disk to a window, bypassing virtual memory completely. 


A text file should contain a single form to be evaluated to create the image. The 
usual form is a call to the function color:make-image. 


For example: 


*** -*- package: user; base: 10; mode: lisp -*- 
(color:make-image ‘color:rgb-image 

‘name “apple” 

properties ‘(:author “ddyer” 

‘date “2//20//86 14:34:18") 

:width 640 

‘height 484 

‘rle ’(color:rle-array-1 color:rld-array-1) 

‘-binary-info ‘(:rle :rld :red :green :blue)) 


File Format 


In this example, the image “‘apple”’ is an RGB-IMAGE, with the properties “au- 
thor” and “‘date.” It is 640 x 484, and run-length/delta-encoded using rle-array-1 
and rld-array-1. The paired binary file contains entries that COR ESDONS to the 
keywords :rle, :rld, :red, :green, and :blue. 


A binary file contains the bit-arrays. You can skip this section unless you need to 
read IMAN’s binary file on a foreign machine, or create IMAN’s binary files on a 
foreign machine for use on a 3600-family machine. 


tl 
- 


Block Format 


An IMAN .dump file’s internal block format is composed of some number of 
logical blocks. Each block represents an object. The general format for a block 
is a simple header followed by a data block, as follows: 


Word 1: A 32-bit integer that indicates the number of bytes in the 
rest of the block, not including this word. 
Word 2: A 32-bit integer that indicates the block type. Because of 


the word count, it is possible to parse the file without 
understanding all the block types. 


Word 3 to end Some number of 32-bit words of “other data” relevant to 
of block: the block type remaining word. Finally, the remaining 
data. 


The block types can be: 


Type Type Number Explanation 


Array 1 1D or 2D integer arrays 
Symbol 2 Lisp symbols 
String 5 Text strings 


Block type array (1) contains this internal format: 


Word 1: Number of bytes remaining. 

Word 2: 1, the array type number. 

Word 3: Bits per element of the array. Can be 1, 8, 16, 32. 

Word 4: Number of dimensions of the array. Can be 1 or 2. 

Word 5: First dimension length. 

Word 6: If 2D, length of second dimension. This word is not present in a 
1D array. 


The rest of the words in the block contain the data for the array, stored row- 
major. 
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The general file format interprets a run-length/delta-encoded array as an 
ordinary array. Other mechanisms interpret arrays as “containing” run- 
length/delta-encoded data. ; 


— Block type symbol (2) has an internal format that is the same as for array 

it blocks, except that the type number is 2. Symbols are always 8 bits per charac- 
ter and 1D, but the fields are present anyway. 

Block type string (3) has an internal format that is the same as for array 


blocks, except that the type number is 3. Strings can be either 8- or 16-bits per 
character, but are always 1D. 


—— 
— 


IE Run-Length/Delta Encoding 


You can skip this section if you are not interested in knowing how to generate 
7 or interpret run-length/delta-encoded data for your own applications. 


IMAN uses a combination run-length/delta code. The exact format can change; 
in principle the system can use many different compression techniques. 


The presence of run-length/delta-encoded data in .dump files is indicated by 
the symbols :rle and :rld in the block stream of the .dump file. A typical .dump 
file contains a sequence of keyword/value pairs like this: 


Block Block Block | | 
is Number Type Data | 


symbol srle nl 


symbol color:rle-array-2 | | | | 


tom , 
= Note: There is no special block type for the run-length/delta-encoded data. ii 
symbol rid | 


CNS NDE BN EIN eet 


symbol color:rld-array-2 
symbol :red 
array #<art-8b-640-484 
67702226> 
— ei symbol :green 
‘im 8 array #<art-8b-640-484 
7 115240000> 
) symbol :blue 
10 symbol #<art-8b-640-484 a 
115467206> | 
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The values associated with the symbols :rle and :rld indicate the names of the 
functions that were used to encode, and that should be used to decode, any 
arrays following in the file. | 


IMAN currently uses two sets of functions to encode arid decode, which differ 
only in a trivial detail. For both, the type of the array containing the encoded 
data is a 16-bit-per-pixel array, with one dimension. The leading few 32-bit 
words in this 16-bit array (composed of pairs of array elements) are a subblock 
that indicates the kind of array to be constructed from the encoded data. 


For rle-array-1 and rid-array-1, the subblock format is as follows: 


The array to be constructed is always 2D and is always an 8-bit-per-pixel array. 


(32-bit) word 1: Width (in pixels) of the array to be constructed. 
(32-bit) word 2: Height (in pixels) of the array to be constructed. 
Rest of subblock: < <encoded-data> > 


For rle-array-2 and rid-array-2, the subblock format is as follows: 


The array to be constructed is always 2D and can be either a 1-bit-per-pixel or 
an 8-bit-per-pixel array, but is always 2D. The width of 1-bit-per-pixel arrays is 
always in multiples of 32 bits. 


(32-bit) word 1: Bits per pixel of the array to be constructed. 
(32-bit) word 1: Width (in pixels) of the array to be constructed. 
(32-bit) word 2: Height (in pixels) of the array to be constructed. 
Rest of subblock: < <encoded-data> > 


The encoding scheme for both format 1 and 2 is as follows: the remainder of 
the data in the encoded array is exactly enough to construct the array, possibly 
with a few leftover bits (< 16). The code used is an instantaneously decodable, 
bit-oriented, variable-length Huffman code, with the following opcodes: 
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Code Explanation | 
fick 1xxxxxxxx Emit the xxxxxxxx as 8 bits of data. | : 
— 000xx Emit the previous 8 bits of data plus xx.(a 2-bit integer). | : 
a OO1xx Emit the previous 8 bits of data minus xx (a 2-bit integer). | 
a 010 Emit a copy of the previous 8 bits of data. 
01110 Repeat. The next opcode is a constant (1xxxxxxxx type) 
. opcode, which is the repeat count. Several “repeat” 
as : ; 
opcodes (with counts) can follow one another directly to 
: construct a larger repeat count. For example, the opcode 
rt stream: 
: 
Constant 6 
—— Repeat 100 
— Repeat 2 
Constant 100 
a Emits (+ (* 2 256) 100 1) = 613 6’s followed by a 1. 
Lis | 
The unused opcodes in this scheme are reserved for future expansion. 
1E 
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Appendix A 
om In Case of Trouble 


x 
ee Problem 


You have trouble creating a color screen. 


What is probably wrong 


The color system software configures automatically to the type of color hard- 
ware and the backplane slots in which it is installed. Your color system software 
cannot read the ID proms that normally identify the hardware, or the ID proms 
contain incorrect part number information. 


What you can do 


First, type the following form at a Lisp Listener: 


(color:color-system-description) 7 


The system should respond with three values: 


‘STANDARD ;; Standard color controller 

1 ;; 1 through 4, depending on how many memory boards 

“you have | 

— (: HIRES-PADDLE) ;; Standard paddle board . 
f 


If the system does not return three values, refer to this table to trace the proba- | 
ble culprit from the symptom: : 


Symptom Culprit | 
No output at all Controller 
Wrong number of memories Color memory board 
(nil) or nil for third value Paddle board 


Bent backplane pins or other mechanical defects can cause any of these | 
problems. 
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On CAD buffer, chroma, and standard paddle boards, an external power con- 
nector must be plugged into the back. The paddle board does not work without 
this external power connection. 


i 


When the output from (color:color-system-description) is‘not as expected, some- 
thing is wrong with the hardware or the way it is configured. Contact your cus- 
tomer service representative to repair the hardware. 


ini 


In the interim, you can tell the software what boards are present and where they 
are. The function you need to call is color:define-color-controller. 


e°@ Problem 


You cannot determine which boards are plugged in and working. 


_ What you can do 


Use the function color:color-boards-present. This function accepts key- 
word :show-paddle-cards to help hardware debugging. It prints the raw in- 
formation read from the color paddle board ID proms in the same format as 
(si:show-configuration). 


The information from color-boards-present is taken directly from the hard- 
ware, and is unaffected by define-color-controller. 


For example: 


(color:color-boards-present :show-paddle-cards t) => 
> (color:color-boards-present :show-paddle-cards t) — 
--->> Note: Invalid checkwords on the LBus slot 05 — PADDLE side. = 


Unknown board type (PN. 4294967295) S.N. 4294967295, manufactured on 2161- 
06-04 

Manufactured as rev 255, functions as rev 255, ECO level 255 — 
Unknown board type (PN. 170388) S.N. 0, manufactured on 1985-02-11 

Manufactured as rev 1, functions as rev 1, ECO level 0 —_— 


CAD buffer paddle (RN. 170314) S.N. 0, manufactured on 1985-05-09 
Manufactured as rev 1, functions as rev 1, ECO level 0 
| ——->> Note: Invalid checkwords on the LBus slot 06 — PADDLE side. - 
| Unknown board type (PN. 4294967295) S.N. 4294967295, manufactured on 2161- 
06-04 
Manufactured as rev 255, functions as rev 255, ECO level 255 | 
( (170314 6) (170388 5) (170388) (170329) (170238) (170144) (170286) = 
(170136 0 3) (170429 5) 
(170140) (170403) (170281) (170324 6) (170314) ). 
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Note: Do not be alarmed by invalid checkwords. Normally only half the 
slots checked by this function are filled in. Also, do not be alarmed by 
“unknown board type.’ Some color paddle board types are unknown to 
the system. | 

Problems 


You try to make a color screen and get the error: 


>> Error: The hardware required to make this color screen 
wasn't found 
No FGRB controller found 


Screen will not expose 


What is probably wrong 


The color system software configures automatically to the type of color hard- 
ware and the backplane slots in which it is installed. Your color system software 
cannot read the ID proms that normally identify the hardware, or the ID proms 
contain incorrect part number information. 


What you can do 


First, you should contact your customer service representative to fix the hard- 
ware. 


In the interim, to override the missing configuration information, you can man- 
ually define an auxiliary method and create a screen to tell the software that the 
hardware it cannot find exists. You do this using the following form: 


WARNING: Use this form with caution. Improper use might crash your machine. It is included 
to allow you to override missing ID proms. 


(color:define-color-controller controller-type backplane-slot 
memories &rest paddle-cards) 


For the high-resolution system: 


(define-color-controller :standard 5 ‘(3 2 1) :hires-paddle) 


For the broadcast-resolution system: 


(define-color-controller :standard 5 '(3) :broadcast-paddle) 


For the frame grabber system (in slot 7): 


(define-color-controller :frame-grabber 7 nil :frame-grabber-paddle) 


In Case of Trouble 
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For the CAD buffer system (in slot 7): 


(define-color-controller :cad-buffer 7 nil :cad-buffer-paddle) 


Note: The slot numbers used in these examples might not match the slot 
numbers on your machine. You must verify the slot number at your site 
before using it in one of these forms. 


The following are internal or low-level functions that you should not need to 
call: 


(color:color-part-numbers) 
(color:color-boards-present) 
(color:find-part-number-slots) 
(color:internal-color-system-description) 
(color:setup-hardware-slots) 


* Problem 


Colors on the monitor are not clear. Picture quality is degraded. 


What is probably wrong 


Too many cable segments in a daisy-chain are causing signal degradation. The 
longer the cable segments, the more pronounced the signal degradation. 


Too many connector couplings are causing signal losses and inducing reflection 
noise. 


Too many or too few terminators are on the cable run. 


What you can do 


Check the stringing of the video cables. The video output (whether it is the 
output of the color system, tape machine, camera, or any other source) must be 
driving only one coaxial cable. 


The driver of the coaxial cable must be at the physical and electrical beginning 
of the cable run. You can daisy-chain that coaxial cable through several devices. 
For example, you can take the output of a color system, daisy-chain it through a 
monitor, and then go to the color encoder. Then, and only then, terminate it. 


The coaxial cable must have only one termination. The cable’s termination must 
be at the physical and electrical end of the cable run. The driver must be at one 
end, the cable segments in the daisy-chain in between, and the terminator at the 
other end. 
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Problem 


Monitor is not syncing to the video. 


What is probably wrong 


The color encoder might be getting sync on its video channels, or you might be 
running the wrong sync program. 


What you can do 


First, turn off the monitor. 


Check the jumper switch on the rear edge of the color paddle boards. The 
jumper switch keeps sync off the video channels and sends it to the color en- 
coder. On chroma paddle boards, the jumper is controlled by the software. 


When a color paddle board is driving a color monitor, the jumper switch must 
be on. When a color paddle board is driving a color encoder, it must be off to 
keep sync off the video channel and get it to the monitor at the same time. The 
only way to do this is to send sync to the monitor over a fourth coaxial cable. 
You can get that sync from the separate jack on the rear edge of the color 
paddle. 


You can send the message :put-sync-on-video to the color screen to check if 
sync is on video under software control. It returns t if it is, nil if it is not, or 
jumper if it is controlled by a jumper switch on the card. 


If the sync is off the video channels, check the sync program you are running. 
The color system has a programmable sync generator that generates a wide 
range of video formats. To check what sync program you are using, send this 
message to the color screen: 


(send color:color-screen :sync-program) => 
sync program tv:pal-sync-program 20621088 


Table A.1 lists the standard sync programs. If you are running the color system 
on a monitor that is not included in this table, you can program the sync genera- 
tor to generate the signal format you need. 


Nondefault Sync Programs 


The standard sync programs reside in the directory color:sync;*.bin. The 
“loaded” names of sync programs are the same as their filenames, and will not 
work if you rename the files. 


In Case of Trouble 


| Sync Program 


tv:cad-buffer-amtron- 
| sync 


tv:cad-buffer-tek-sync 


tv:cad-buffer- 
universal-sync 


tv:cad-buffer-3d-sync 


tv:color-sync-1024- 
lines 


tv:color-sync-24fps 


tv:color-sync-512- 
nonint 


tv:color-sync-768- 
nonint 


tv:color-sync-hdtv 


tv:color-sync-ntsc 


_ tv:pal-sync-program 
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Table A.1 Standard Sync Programs 


Type of Monitor 


Use with an Amtron monitor. 
Use with a Tektronics monitor. 


Use with either an Amtron or 
Tektronics monitor. This program is a 
compromise between the two 
previous sync programs; however, the 
picture does not center correctly. 


Use with a stereo liquid-crystal 
frontpiece. 


Use with a high-resolution monitor. 


Use only with a 24-frames-per-second 
VTR, which records and plays back 
video in synchronization with a movie 
camera. 


Use with a standard high-resolution 
monitor. 


Use only with a Mitsubishi high- 
resolution monitor. 


Use with a high-definition TV monitor. 


Use with a low-resolution monitor 
without a genlock paddle board. 
Acceptable to all monitors and VCRs 
designed for interlaced NTSC 


_ standards. Use with standard, chroma, 


and broadcast paddle boards. 


Use with high-resolution and 
broadcast-resolution color systems. 
This program trades a larger picture 
area against the increased flicker of 
50 Hz, so it can be used even when 
compatibility with PAL broadcast 
signals is not required. Compatible 
with common European video 
formats. This program is an exception 
to other PAL programs in that the 
pixels are square. 


Screen Resolution 


1024 x 1024 at 60 Hz 
interlaced 


1024 x 1024 at 60 Hz 
interlaced 


1024 x 1024 at 60 Hz 
interlaced 


512 x 512 at 60 Hz 
interlaced 

1280 x 1024 at 60 Hz 
interlaced 


640 x 600 at 48 Hz 
interlaced 


640 x 512 at 60 Hz 
noninterlaced 


1024 x 769 at 50 Hz 
noninterlaced 

1248 x 1024 at 60 Hz 
noninterlaced 


640 x 480 at 60 Hz 
interlaced 


864 x 575 at 50 Hz 
interlaced 


Table A.1 Standard Sync Programs continued 


Sync Program Type of Monitor Screen Resolution 
tv:pal-narrow-sync- Use with an NTSC monitor. This 640 x 575 at 50 Hz 
program program has a 1.1:1 aspect ratio.* interlaced 
tv:genlocked-pal- Use with an NTSC monitor with a 640 x 575 at 50 Hz 
narrow-sync-program genlock paddle board. This program interlaced 


has‘a't) 1 leaspectsratio.” 


no tv:genlocked-pal- Use with an NTSC monitor with a 864 x 575 at 50 Hz 
sync-program genlock paddle board. interlaced 
tv:genlocked-sync- Use with a low-resolution monitor 640 x 480 at 60 Hz 
ntsc with a genlock paddle board. interlaced 
tv:color-sync- Use with an NTSC monitor. 640 x 484 at 60 Hz 
broadcast-ntsc interlaced 
tv:pal-broadcast-sync- Use with an NTSC monitor. This 640 x 575 at 60 Hz 
program program has a 1.1:1 aspect ratio. * interlaced 
tv:genlocked-pal- Use with an NTSC monitor with a 640 x 575 at 60 Hz 
broadcast-sync- genlock paddle board. This program interlaced 
program has a 1.1:1 aspect ratio. * 
tv:genlocked-sync- Use with an NTSC monitor with a 640 x 575 at 60 Hz 
broadcast-ntsc genlock paddle board. interlaced 
tv:frame-grabber- Use with an NTSC-type monitor. 640 x 484 at 60 Hz 
sync-program interlaced 
tv:pal-frame-grabber- | Use everywhere pal-sync-program is. 640 x 582 at 50 Hz 
sync-program Can be used with the frame grabber. interlaced 


*A sync program with an aspect ratio of 1.1:1 stretches pixels in the x direction, causing them to 
be slightly oblong. All other sync programs have square pixels. 


If you specify a general type of sync program rather than the exact sync program name, the 
color system automatically selects the correct sync program for the hardware you are using. 
The following are the general types of sync programs: 


:pal PAL format sync program with 1.4:1 aspect ratio, if supported by 
the frame buffer 
PAL with 1.1:1 aspect ratio 


:narrow-pal 


:ntsc NTSC format sync program 
shires 1280 x 1024 sync program 
:hdtv 1248 x 1024 sync program 


example: (color:make-color-screen :sync-program :pal) 


> 
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To specify a nondefault sync program, specify a :sync-program ‘name key- 
word argument to the make-color-screen function. For example: 


(make-color-screen :sync-program ‘tv:genlocked-sync-ntsc) 


The color system looks for a sync program that is already loaded. 


(get ‘color:sync-programs 'tv:genlocked-sync-ntsc) 


If the sync program is not found, it loads this file: 

(load “color:sync;genlocked-sync-ntsc. bin’) 
You can preload sync programs; they are just ordinary binary files. The function 
color:load-sync-programs loads the available sync programs. 


Note: Some of the color setups specify a default sync program. To override 
the default, specify the sync program last in the argument list. The last 
sync program specified ts the one actually used. 


Creating a New Sync Program 


The file color:sync;syncgen.lisp contains the logic and definitions for all of 
the standard sync programs except for the CAD buffer. The CAD buffer sync 
programs are defined in color:sync;cad-buffer-sync-gen.lisp. 


These programs are not products. They are provided as examples of sync pro- 
grams that can be adapted for use with an unusual monitor. 
Problem 


You cannot execute a framegrab. 


What is probably wrong 


Frame grabbers do not grab unless they see proper sync on their inputs. Assum- 
ing video is really “out there somewhere,’ the most common errors are incor- 
rect cabling and incorrect sync switch position. 

What you can do 


Check the cabling. The BNC connectors on some frame grabber paddle boards 
are not labeled. They should be in the following order, top to bottom: 
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-~ Sync (Out) 

External trigger (in) 
Red (in) 

Green (in) 

Blue (in) 


= Sync (in) 

- Sync can be supplied from either composite sync on the green input or from a 
separate sync-only signal on sync-in. A small blue jumper labeled ‘‘sync sel” on 
the paddle board determines which source of sync is in use. If the jumper is not 
in the right position, the frame grabber will not grab. Place the jumper in the 
“up” position for sync on green. 


ee Problem (Only applicable if you are using a VMS file server) 


You cannot store images. The file server loses track of the file length. 


What is probably wrong 
The VMS SYS host loses track of the file length of the .dump file. 


What you can do 


Install the following patch. 


In the file color:images;dump.lisp, in the function read-from-dump-file, 


change: WHILE (FIXP LEN) 


to: WHILE (AND (FIXP LEN) (NOT (ZEROP LEN) )) 


e°e Problem 


You cannot make a genlocked screen. 


What is probably wrong 


The genlock board is incorrectly installed or the color controller has a wrong 
PAL and does not know about the genlock board. 


What you can do 


Verify that the genlock board is installed in the slot behind the color controller. 


Check that the part at location U19J (etch board) is PAL LBMIO2.2. If it is any 
other part number, replace the PAL. 
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In the meantime you can manually create a screen by using the following form: 


WARNING: Use this form with caution. Improper use might crash your machine. It is included 
to allow you to override missing ID proms. 


(color:define-color-controller controller-type backplane-slot 

memories &rest paddle-boards) 
The following form shows what might be typed for a broadcast-resolution color 
system with a genlock board: 

(color:define-color-controller :standard 5 ’(3) 

‘broadcast-paddle :genlock) 
To make sure the screen is genlocked, type: 

(send color:color-screen :sync-program) 


When the genlock is properly installed, this function returns an object that con- 
tains the words genlocked screen. 
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Graphics Mixin Methods 


The following messages can be sent to windows that include (mixin) 
tv:graphics-mixin. 


:draw-simple-ellipse cenier-x center-y half-width half-height Message 


&optional alu 
Draws an ellipse with its axes aligned to the window's coordinate system, 
with specified size. This is :draw-simple-ellipse rather than :draw- 
ellipse because the axes of the ellipse are aligned to the window system’s 
coordinate system, which has much more restriction than a general ellipse. 


:draw-filled-in-simple-ellipse center-x center-y half-width Message 


half-height &optional alu 
Draws a filled-in ellipse with its axes aligned to the window’s coordinate 
system, with specified size. This is :draw-filled-in-simple-ellipse rather 
than :draw-filled-in-ellipse because the axes of the ellipse are aligned to 
the window system’s coordinates, which has much more restriction than a 
general ellipse. (See ellipse example.) 


:draw-convex-polygon dlu x0 yO x1 y1 x2 y2... Message 


Draws a polygon that is convex from the perspective of its first vertex. This 
message is fast and does not cons. 


:draw-polygon dlu x0 yO xl y1 x2 y2... Message 
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Draws an arbitrary polygonal shape, filling in its interior. It need not be 
convex from the perspective of its first vertex; twisted and overlapping 
cases are handled correctly. This message conses and is not as fast as :draw- 
convex-polygon. (See polygon example.) 


Example—Polygons drawn with tv:alu-setz. 


Creating a simple triangle 


(send poly-window :draw- 
polygon tv:alu-setz 60 50 Ret coat: 
600 80 400 300) Slee aan AG 

es 
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Adding a new vertex 


(send poly-window :draw- 
polygon tv:alu-setz 60 50 
500 80 350 300 100 
200) 
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Creating a concave polygon by 
moving the vertex toward inside 


(send poly-window :draw- 
polygon tv:alu-setz 60 50 
500 80 350 300 100 nS Roe SP. 
200 350 150) Re eee 
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Moving the vertex further inside ie ee 
oh 


om 


(send poly-window :draw- 
polygon tv:alu-setz 60 50 
500 80 350 300 100 
200 400 150) 
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Moving the vertex further until it ; 
extends outside. Note the result of DUS nea 
the “parity fill rule.’ Orie 


(send poly-window :draw- 
polygon tv:alu-setz 60 50 
500 80 350 300 100 
200-550-150) 


Creating a concave polygon 


(send poly-window :draw- 
polygon tv:alu-setz 60 50 
500 80 350 300 100 
200 400 150) 


Creating a concave polygon with 
two new vertices 


(send poly-window :draw- 
polygon tv:alu-setz 60 50 
500 80 350 300 100 
200 400 150 230 100 
200 120) 


Moving vertices to overlap one 
edge 


(send poly-window :draw- 
polygon tv:alu-setz 60 50 
500 80 350 300 100 
200 400 150 230 100 
250 250) 
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ee Example—Ellipse drawn 
with tv:alu-setz. 


A mts 


(send poly-window :draw- 
filled-in-simple- 
ellipse : 
300 160 250 100 
tv:alu-setz) 


pn 


The remainder of this appendix describes the :fill-area message and its key- — 
word arguments. 


neat 


:fill-area seed-x seed-y &rest keywords Message 
This message provides a way to perform graphical operations on arbitrarily 
shaped regions of a window based on the pixel data already in the window. 
It is particularly useful for dealing with nongeometric shapes such as those 
produced by freehand sketching or those found on framegrabbed natural 
images. 


| 


:fill-area starts at a designated seed location and searches along rows and 
columns from that location until a specified boundary condition is met. A 
specified function is invoked for each horizontal row in the filled area. Each 
row is found exactly once, though in no particular order. 
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i The keywords for :fill-area define the region to be drawn on by finding 
| connected pixels which either “currently have pixel value x” or “currently 
do not have pixel value x.” 


:fill-area takes two mandatory arguments, seed-x and seed-y, which specify 
the x and y locations within the window to start the fill. 


ee ree ee eee ee ee Oe 


ee ee 


:fill-area also accepts any number of these optional keyword arguments (as 
keyword/value pairs): 


a pn gle a a ame 


:Search-function arg arg can be :until, :while, or a function. 
The default is :until. If a function is sup- 
plied, it must take three values (y-coordi- 
nate, starting-x-coordinate, maximum-x- 
coordinate) and return two (leftmost-x- 
coordinate, rightmost-x-coordinate). The 
following example is the definition for the . 
search function used by :until. 
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(defun scan-for-new-edge-until (row starting-point right-limit 
&aux 
(color *fill-source-pixel-value*) 
(source “fill-source”) 
;The array being filled 
(mask “*fill-pixel-mask*) ) 


(prog scan (left right) 
;; See if we have to scan right or left to find the left edge. 
(if (# (logand mask (aref source starting-point row) ) 
color) 
;we're inside = scan left.. 
(setq left (1 + (scan-left-until-color source color 
row starting-point 
*fill-left-limit*) ) ) 


;;else.. we're outside = scan right to find left edge. 
(setq left (scan-right-while-color source color row 
starting-point right-limit) ) 
(when (> left right-limit) ‘didn't find end of border. 
(return nil) ) ) 
;; Got the left edge, now get the right.. 
(setq right (scan-right-until-color source color row 
(max left starting-point) | 
*fill-right-limit*) ) | 


(return (values left (1- right) ) ) ) ) 


The functions scan-left (/right)-until(/ 
while)-color take five arguments: array- 
being-filled, pixel-value, y-coordinate, 
start-x, and limit-x. In the -left case, limit-x 
must be less than start-x; in the -right case, 
limit-x must be greater than start-x. These 
functions are useful only to match exact 
pixel values under a mask; if you want a 
more complex search function, you must 


| 


= write one. 
we : 
:draw-row-function arg Invokes the specified function for each hor- 
izontal line segment. It is called with three 
irl arguments: y-coordinate, low-x-coordinate, | 


and high-x-coordinate. These coordinates | 
are in “outside’’ coordinates and must be | 
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adjusted by the window’s margin widths. 
For example: 


#'(lambda (line from to) 
(send “*fill-window* :draw-rectangle (- to from -1 ) 1: 
(- from “*fill-window-left*) (- line *fill-window-top*) 
fill-alu) ) 


Specifying ‘IGNORE as the :draw-row- 
function causes the fill to be a noop, 
which is useful if you are interested only in 
the side effects of :fill-area on a bit-array 
you supplied. 


:pixel-value fixnum pixel-value is used by the search functions 
:until and :while. The fill operation begins 
at the seed pixel and continues through all 
adjacent pixels until (or while) the pixels 
with specified value are present. The fill 
does not connect diagonally touching pixels 
unless :connect-diagonals is t. The de- 
fault pixel value is 0. 


:pixel-mask fixnum The match function for :until and :while 
is (= (logand pixel-mask) pixel-value). If 
pixel-mask is omitted, the appropriate 
mask for the window is used. 


:connect-diagonals t-or-nil 
Specifies whether to consider diagonals to 
be connected, and fill across diagonal con- 
| nections. The default is nil, meaning diago- 
nals are not considered to be connected. 


:draw-row-message symbol 
Can be used instead of :draw-row- 
function to send a message to the win- 
dow being filled. The message specified by 
symbol is sent with three arguments: y- 
coordinate, low-x-coordinate, and high-x- 
coordinate. For example: 


Tt al ae 
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| 

(if (list :draw-row-message) 
(lexpr-send self (car message) | 
y-coord from-x to-x (cdr message) ) | 

(send self message y-coord from-x to-x) ) | 

| 


:fill-pixel-value fixnum Causes :draw-row-function to default as | 
if :draw-row-function were a number. ! 
:fill-pixel-value must specify a fixnum ar- | 
gument. In any case, it is bound to tv:* fill- | 
pixel-value* for the use of the fill | 
function. The default fill-pixel-value is | 
(lognot pixel-value), so the default fill func- | 
tion complements the pixel value of the | 
filled area. | 


:fill-alu alu Can be used instead of :draw-row- | 
function to send the window an appropri- 
ate :draw-rectangle message using the 
supplied ALU object for each row segment. 


The following four keyword arguments restrict the fill operation to a rectangular 
area within the window. The default is the entire “inside” of the window. The 
rectangle eligible for filling is from left to (1- right) and top to (1- bottom), 
matching the window system convention. | 


sleft x Specifies the x-coordinate of the left edge of 
the rectangle. 


right x Specifies the x-coordinate of the right edge 
of the rectangle. | 


:top y Specifies the y-coordinate of the top edge of 
the rectangle. 


:bottom y Specifies the y-coordinate of the bottom 
edge of the rectangle. 


:edges source source is a list of four edges (:left x, :top y, 

:right x, :bottom y) that specify the rec- 

vw] tangle coordinates to use to restrict the fill 
ee operation. 
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sbit-array array 


:Save-bit-array (-or-nil 


:discard-bit-array array 


:incrementally-clear t-or-nil 


:Save-line-array ¢-or-nil 


:discard-line-array array 
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:fill area requires a 2D 1-bit array at least as 
large as the potential fill area. :bit-array al- 
lows you to supply one. If you do not spec- 
ify :bit-array, 4°temporary array is 
allocated and used. 


If you specify :bit-array, the area eligible 
for filling is clipped to fit within the bound- 
aries of :bit-array, offset by the effective 
values of the :left and :top edges. 


Returns an automatically allocated :bit- 
array as the value of :fill-area, rather than 
deallocating it. When finished with this ar- 
ray, it might then be deallocated by supply- 
ing the :discard-bit-array keyword 
argument. 


Deallocates the bit-array supplied with the 
:bit-array keyword. It must be one you 
originally allocated with the :save-bit- 
array message in an earlier call. 


Clears the bit-array line-by-line as each new 
line is touched. Defaults to t. Normally, :bit- 
array is cleared before the fill operation 
starts. However, if you supply a bit-array 
and specify :incrementally-clear nil, the 
bit-array is not cleared line-by-line as each 
new line is touched. :incrementally-clear 
can also be a 1D array of type art-boolean, 
which serves as a map of the lines of :bit- 
array. 


Similar to :save-bit-array but returns an 
automatically allocated :line-index-array 
foritne linesimdcx.drray created se Dy 
:incrementally-clear t. The index array is 
returned as the second value. 


Deallocates the line array you supply. It 
must be one you originally allocated with 
:save-line-array. Similar to :discard-bit- 
array. 


it 


Note: For ease of use, omit both :bit-array and :incrementally-clear. 
:fill-area handles them automatically, with a small penalty in 
performance, which is only significant in very demanding applications. 
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Appendix C 
Color Demonstration Program and Testing Procedures 
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This section is intended to guide you through the color demos and patterns that 
serve as a test for all Symbolics color systems. 


Each pattern and demo is specifically designed to check a particular part of the 
color system. The following paragraphs describe the problems that might occur 
in the various test programs. The causes of those problems are also discussed. 


Compare each program with the accompanying color plates, which show the 
correct screen images for each of the patterns and demos. In general watch for 
obvious problems such as the following: 


» Gross errors such as the wrong color, holes, or other flaws in the picture. 


>» Unstable elements, such as scintillating pixels, color fringes, and swim- 
ming scanlines, that occur when the picture should be unchanging. 


» Unstable elements such as snow that occur only when the picture is 
changing. 


Any problem that recurs only in a particular part of the screen is probably 
caused by the monitor. Check the position of the monitor’s termination 
switches. Make sure the monitor is properly converged and degaussed. 


Roll bars, picture wavering, or reflections that cannot be corrected at the moni- 
tor might be caused by faulty or improperly installed cabling. Refer to Chapter 2 
in the Color Graphics Hardware Installation Guide for the proper installation 
of cabling. 


If the problem cannot be solved at the monitor or the cabling and if it appears 
that the cause of the problem is defective image memory or color maps, replace 
the board that is causing the problem. 


The patterns and demos test the 8- and 24-bit systems. Some tests appear signifi- 
cantly different when run in 8-bit mode, but in general the only difference be- 
tween the tests is that the 8-bit version has fewer colors and harder edges 
between colors than the 24-bit version. 


If the color system supports hardware overlay, run the auxiliary hardware over- 
lay test that is described at the end of this section. 


_ 
_—_ 


Creating the Color Screen 


Load the color demonstration system. Type the following to a Lisp Listener 
window: 


(make-system ‘color-demo :nowarn) 
(color:demo) 


The first time a color screen is created, a menu of screen configurations appears. 
Select the screen type supported by the monitor. 


After the color screen is selected, a menu offers to create a series of patterns or 
demos. Run the patterns first, in the order given in the following paragraphs. 


Unless otherwise noted in the mouse documentation line, press any key or click 
any mouse button to stop the program and get back to the color demonstration 
menu. Move the cursor off the menu to stop the color demonstration system. 


Test Patterns 
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Standardize Color Maps 


This program resets the color maps. It is not a test, and nothing appears on the 
screen. It simply loads the color maps with a standard setting of colors. 


This program is useful because each of the patterns and demos changes the 
color values stored in the color maps. Certain programs require the standard 
settings and do not look right or have incorrect information (such as mislabeled 
colors) if the standard settings are not loaded. 


Test Colors and Gray Scales 


This pattern consists of several color ramps and rows of color chips. The top 
row consists of colored chips, each labeled with its color. Immediately below 
the color chips are intensity ramps for the primary colors. On a 24-bit system 
the ramps are continuous; on an 8-bit system there are visible transitions be- 
tween colors. Below the color ramps are chips of gray. The center row consists 
of gray intensity ramps. The bottom four rows are a mirror image of the top four 
rows. 


Look for: 


» Impure colors such as reds that look orange. Impure colors can be 
caused by incorrectly connected RGB cables. 


» Fringes between colors. Color fringes can indicate a convergence prob- 
lem with the monitor. 
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Test Grid 


This pattern consists of a rectangular grid of lines and circles. 


Look for: 


>» Color fringes on the solid white lines. Fringed lines can indicate a con- 
vergence problem on the monitor. 


> Lines that move out of position. Swimming lines might be caused by a 
problem with the power supply. 


» Artifacts near the edges of the screen and ghost pixels outside the left 
and right margins. Ghost pixels are usually caused when there is trouble 
initializing the video pipeline. 


» Lines whose vertical components jitter back and forth. 


Resolution Chart 


This pattern consists of rows of alternating black and white rectangles. The 
rectangles at the top and bottom of the screen are wide and become progres- 
sively narrower toward the center of the screen until the rectangles are one pixel 
wide. 


Look for: 


» Indistinct boundaries between the black and white regions. Shadowy 
transitions can indicate a problem with the monitor. Although the transi- 
tions between the black and white regions in the center row might be 
hard to see and there might be a slight moire pattern effect, it should be 
clear that the center row is not a uniform color. 


Rectangles that are not solidly black or white. This type of error is most 
common in the two or three narrowest rows of rectangles and can indi- 
cate a problem with the fill-mode hardware. 


Color Intensity Ramps 


This pattern consists of three color ramps, one for each of the primary colors. 
The fourth pane on the bottom shows the grid outline for the ramp panes. 
Sharp changes to the intensity of the colors in the ramps should occur at posi- 
tions indicated by the grid lines. On a 24-bit system, all three ramps are dis- 
played simultaneously. On an 8-bit system, all three ramps display the same 
color; a submenu allows you to change the color. 
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Look for: 
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» Vertical lines that are not indicated on the grid outline as well as interrup- 
tions to the steady left-to-right progression in intensity. Both conditions = : 
can indicate problems with the color maps. 


> Color fringes at color-intensity edges. Color fringes can indicate slow 


DACs. = 
Show Color Map 
This pattern also consists of color ramps, but unlike the Color Intensity Ramps, 3 | 
it shows the colors currently loaded in the maps rather than displaying a special 
- color map computed for the test. On a 24-bit test, the ramps are continuous; on 7 , 
an 8-bit test, you can see transitions between the intensity levels of the colors. . 


The top row of each ramp is drawn; bitblt is then used to “smear” the top row 
to the rest of the ramp. 


Look for: 


» Flaws in the copied part of the ramps. If the top row is not copied con- 
sistently over the rest of the ramp, there might be trouble with reading in 
pixel mode (24-bit system) or packed mode (8-bit system). 


Edit Color Maps 


This program is also a series of color ramps, except that you are first prompted q 
with a menu that allows you to change the color values stored in the color bo 


maps. 


It is recommended that you run Standardize Color Maps after editing the color 
maps since subsequent patterns might not look right with the colors you have 
loaded. 


Color Mixing 


This program tests the four ways of mixing color: opaque, inclusive-or, 
exclusive-or, and additive. 


RGB Cube, Hexcone Cube, Shaded Circles 


= 


Check that these patterns correspond to the photographs and that there are no - = 
obvious flaws in the patterns. 
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Color Demos 


Spheres Demo 


This demo is different for each system since it demonstrates hardware features 
of the individual color systems. The hardware feature being demonstrated is 
shown in text at the bottom of the screen. This demo always runs in 8-bit mode, 
even on 24-bit screens. 


The basic pattern is divided into four rows, one each of white, red, green, and 
blue spheres. Each sphere is surrounded by dark shades of color that become 
progressively less shaded toward the center. 


Animate Color Map. In the first part of this demo, the spheres switch from 
shaded to inverse-shaded and back to shaded. The colors of the rows then 
change so it appears that each row of colored spheres is moving up in the pat- 


1 tern. 
An Move Individual Lines. Several lines that contain text and spheres do a slow 
1 scroll, eventually returning to the original position. 
a Pan Individual Lines. The top lines of the screen contain the text Symbolics 
Ue and pan slowly to the left. 
i Zoom Individual Lines. The top lines of the screen contain the text Sym- | 
i bolics and zoom on the x axis until the text is very wide. il 
Ee Global Pan and Zoom. The top lines zoom on the y axis until the text is tall a 


i s and narrow. Global pan is used to move the image in a circular motion. Global | | 
zoom enlarges one of the red spheres until only a few pixels fill the screen. | 


1v Hardware Cursor. The hardware cursor is present only on the standard color 
paddle board. A large cursor takes several random walks along the screen. The 
cursor is transparent except for a solid white border and an S in the center that 


ie intensifies the color it passes over. 
| = 
Look for: 
1 > Glitches in the image as the color maps change. 
1 ie 


> Impure colors on the 24-bit screen. Impure colors might indicate a prob- 
lem with the map source register. 


» Changes to the original pattern after each of the hardware tests. 
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Color Mandala, Color QIX 
These demos are variants of the QIX program from (hacks:demo). 
Look for: 


» Artifacts left on the screen as the pattern runs. Artifacts left on the screen 
can indicate that color pixel memory is not reliable. 


Finger of God 


This demo consists of letters and shapes that are written over one another. 
When a pattern is erased, the patterns it occluded should appear from under- 
neath it. The order of the patterns, from the back of the screen, is as follows: 

Background 

Drop-shadow 

Triangular Grid 

Light Outline Letters 

Heavy Outline Letters 


Solid Letters 
The patterns at the bottom of the list obscure patterns above them in the list. 
For example, the heavy outline letters obscure the light outline letters and are in 
turn obscured by the solid letters. When a pattern is erased, the pattern below it 
in the list reappears unchanged. For example, when the triangular grid is erased, 
the drop-shadow or background below it reappears. 


Look for: 


» Patterns that are not opaque. Problems with opacity can be caused by 
problems with color map overlay or use of the plane mask to control 
which pixels are written. 


Triangles, Movie, Ballantine, Snake, Symbolics Logos, Munching 
Spheres 

These demos are a series of constantly varying colors and patterns that change 
as the data in the color maps change. Watch for obvious errors. 

Color Editor 


This demo forces loading of the color editor system. Watch for glitches in the 
video as the color maps change. 
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Load or Save Image, Mandelbrot Images 


These demos force loading of the IMAN system. Menus guide you through the 
steps. Loading and saving images exercises use of pixel mode in a 24-bit high- 
resolution system. 2 


Grab Frame 


If a frame grabber is installed in the color system, use this menu choice. If the 
frame grabber is connected properly, the framegrabbed image appears on the 
monitor screen. 


Pan and Zoom Using the Mouse 


This demo tests the global pan and zoom. Perform this test after loading an im- 
age (the image can be one of the test patterns). 


Use the mouse to pan and zoom the color screen. (L) to enlarge the view, (R) to 
diminish the view, and (M) to stop the program. 


Look for: 


> Settings of pan and zoom where part of the screen starts scintillating. 
Scintillating lines usually indicate slow PALs in the pixel replication pipe- 
line. 


Mouse Pan/Zoom Window 


This demo tests the software capabilities of the mouse. Run this test with an 
image loaded on the screen. 


A small corner appears on the color monitor. Click any mouse button to create a 
window. Move the mouse to change the shape and size of the window. When 
the window is the shape and size you want it, click any mouse button to create a 
viewing window. There are now two windows on the screen. As you move the 
mouse window, the pixels within the mouse window appear in the viewing 
window. Use the mouse buttons as in the Pan and Zoom Using the Mouse demo 
to increase or decrease pixel size. The zoomed pixels appear in the viewing 
window. 


Use this test to get close-up views of pixels you suspect are faulty. If the error is 
caused by data, the zoomed view enlarges the error. If the error is caused by a 
defective pixel on the monitor, the enlarged view, except for the faulty monitor 
pixel, appears correct. 


Look for: 


» Pixels that appear different after they are zoomed. Such an error can | 
indicate a problem in the video pipeline. | 
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> Pixels that are different from surrounding pixels in a block of color. This 
type of problem can be caused by an error in image memory. 


Wandering Window 


Create a window as you did in Mouse Pan/Zoom Window. The mouse window 
moves automatically around the screen, and the pixels over which the mouse 
window passes are shown in the viewing window. 


Auxiliary Overlay Test 


This program tests the overlay capability of those configurations in the high- 
resolution and broadcast-resolution color systems that support hardware over- 
lay. This test should be run after the color demos and patterns. 


Load the overlay test program. Type the following to a Lisp Listener: 


(make-system :map-test-system :nowarn) 


Press SELECT R. 


In the lower-right corner are test choices for the program. Use [Create the Color 
Window]. 


After the color window is created, test choices for configurations supported by 
the installed color system appear in the lower-right box. You can run the tests 
individually or use [Loop all the Tests], which runs all configuration tests one 
after another. If you loop all programs, text in the lower-left box indicates the 
test that is running. 


The test programs divide the black-and-white monitor into several columns, one 
for each color map in the color system. As the test runs, a column or columns 
on the black-and-white monitor are filled or partly filled with patterns. These 
patterned rectangles should correspond to the location and color of rectangles 
that appear on the color monitor. (A key to the patterns and colors appears be- 
low the color map columns.) The test takes up only a fourth of the color moni- 
tor. 


The 12-bit test (included only with the broadcast-resolution color system) looks 
different from the other tests. It consists of only a few narrow, vertical lines. As 
with the other tests, check that these patterns, though they might be hard to 
see, correspond to the colored lines on the color monitor. 


The 8- and 12-bit tests change the color maps so that the color system runs in 


Before ending the color test programs on a 24-bit system, run the 24-bit test. 
those modes. You must run the 24-bit test to reset the color system to full color. 
F 
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Chroma key blanking 


The chroma key blanking program is not included in the loop program and has 
to be run individually. This program tests that the color system properly blanks, 
that is, erases specified colors from an image. 


Before selecting this program, it is recommended that you run Standardize 
Color Maps and load Test Colors and Gray Scales (both are accessible on the 
color demo menu). The chroma key blanking program should not be run imme- 
diately after the 12-bit test. 


As the program is loaded, the color map columns disappear and are replaced by 
a series of dashes and horizontal lines. The unbroken horizontal lines break the 
window into rows that correspond to the number of color maps; the dashes 
correspond to bits in the color maps and thus to colors in the image on the 
color monitor. 


Colors can be blanked at either the black-and-white or the color monitor. At the 
black-and-white monitor, (L) on the short dashes that represent bits (a blanked 
bit is shown as a bold dash). You should see certain colors disappear from the 
color image. The bits are roughly in the same location on their screen as are the 
colors to which they correspond on the color screen. (R) to undo the blanking. 
Plate C.3 is a sample chroma key blanking test where certain bits have been 
blanked on the black-and-white monitor; plate C.2 shows the corresponding 
color monitor. 


To blank colors from the color monitor, press FUNCTION X to move the cursor to 
the color monitor. (M) to bring up a menu; select [Select Blanking on Color Win- 
dow]. Position the mouse over one of the solidly colored chips and (L). That 
color should disappear from the screen, and the bit to which the color corres- 
ponds should be shown as a bold dash on the black-and-white screen. Other 
colors might also disappear from the color screen. (R) to undo the blanking. 


Chroma keying 


To test chroma keying, unhook the R (red) cable from the monitor and replace it 
with the key output cable. All red disappears from the image. Now when a color ! 
is blanked, the area filled by that color turns red. 


The chroma key blanking program also provides a way to test the decoding of a 
pixel. While still in the chroma key blanking program, (M) to bring up a menu. 
Use [Sample Colors on the Color Screen]. With the mouse on the color screen 
(it might be hard to find the mouse because unusual color maps and display 
modes are in use), (L). 


The message that appears describes the color bit under the mouse. The follow- 
ing message is an example of what might be read: It 
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sample at 543,430 is 200776 
Ov 0 R=376G =0 B= 1 ; 
vis (from map 15) R=0.0 G=0.0 B=1020.0 


The first line identifies the location of the pixel along the x and y axes and gives 
the pixel value. The second line shows the overlay values. In this example, the 
overlay bits are zero, and the bits associated with the red channel are 37 Onlunic 
last line shows the value for the color seen on the screen and the color map in 
which the value is stored. This line takes overlays and the actual color maps into 
account. 


Press SELECT L to escape from this test program and return to the Lisp Listener 
window. 
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Color Intensity Ramps, 8-bit version Color Intensity Ramps 24- bit version 
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Show Color Map, 8-bit version 


Color Mixing, 8-bit version 


RGB Cube, 8-bit version 
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Show Color Map, 24-bit version 


Color Mixing, 24-bit version 


RGB Cube, 24-bit version 
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Hexcone Cube, 8-bit version Hexcone Cube, 24-bit version 


Shaded Circles, 8-bit version Shaded Circles, 24-bit version 


Spheres Demo Color Mandala 
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Mandelbrot Images Wandering Window 
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Plate C.1 24-bit overlay test, Plate C.2 Bianked colors on color screen, 
high-resolution color system high-resolution color system 
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Plate C.3 Bianked bits on black-and-white screen, high-resolution color system 
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Appendix D eS 
Using Icons in Menus 


This appendix describes extensions to the menu system that permit icons as 
well as text in menus. These changes are part of the standard operating system 
world load; they are described here because they are not yet documented in the 


7 standard system documentation. | 
Loading the Menu System Extensions i 
in| The functionality documented here is integrated into the base system and so is ey 
, already present. You do not have to load anything. | | 
7 What Changed? ea 
In previous releases, menu items could be strings or symbols. Menu items can | ao 
ik now be instances. al eae 
~- cA be 
ite If the menu item is an instance, it must accept the following messages: | a 
ia :menu-bounding-box-size window stop-x Message ae 
= Returns two values, xsize and ysize, for the space needed to display the oF 
item. window is the menu being built. stop-x is the right margin. cas 
| eg. 
— 5 
in :menu-print window x y Message a r 
a Displays the menu item itself, in the area bounded by x, y and its bounding Ki Sy 
box size. window is the menu being refreshed. x and y are the upper-left et: 
' corner of the box assigned to the item. re 
a 9 
:menu-blinker-edges window Message | a 
— Returns the left, top, right, and bottom edges for the blinker relative to the | ce 
— bounding box. window is the menu being refreshed. This message is op- tee) 
tional, so the instance need not accept it. It can return nil to use the default ap 
— bounding box size. es 
i | j ei 
Le 
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ee Example—Present a menu of stipple patterns. — 


This example defines the function choose-stipple, which presents a menu of 
stipple patterns, displayed as boxes filled with sample swatches of the stipple. 


(defflavor box-menu-item ((text “ ”’) (width 0) (height 0) stipple) ( ) 
‘Initable-instance-variables) 


(defmethod (:menu-bounding-box-size box-menu-item) (win &optional stop-x) 


stop-x ;not used 
(multiple-value-bind (xs ys) ‘ 
, | (send win ’:compute-motion text O nil 0 0 ) ‘the size of the text string 3 
; | (incf ys (send win ':line-height)) ;plus line height 
a | ‘make the box width allow for extra space on the left and right, 
Ls ) sand make the box height 50% greater than the height of a line 
- | (values (+ xs (send win :compute-motion * ” 0 nil O O)) | 
.—l Te (+ ys (// ys 2))))) - 


(defmethod (:menu-print box-menu-item) (window x y) 


| (multiple-value-bind (cx cy) (send window :column-row-size) 2 
q ‘fill the whole box allocated to the item with the stipple pattern 
aE | ‘this is the “right” thing except for fill mode menus &E 
(send window :bitblt alu-seta cx cy stipple 0 0 (— x ( \ x cx)) (- y( \ y cy)))) — 


| (multiple-value-bind (xs ys) (send self ’: menu-bounding-box-size window) 
| f ‘empty a rectangle for the text to be drawn in. 
| (let ((Space (send window :compute-motion * ” 0 nil 0 O))) 


(send window :draw-rectangle 


cages eh bes | et 


(— xs space space) (// (* ys 2) 3) a 
(+ x space) (+ y (// ys 6)) & 
| tv:alu-setz) | 
| — 
| (send window :set-cursorpos (+ x space space) (+ y 1 (// ys 6))) = 
> | (send window :string-out text) | 
| ))) a 
_ — 
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(defun choose-stipple ( ) 
(tv:menu-choose 
(loop for gray-name in tv: * gray-arrays* ;*grays-arrays™ is a list of standard stipples 
as gray-array = (symeval gray-name) | 
collect 
(if (arrayp gray-array) 
‘(,(make-instance ‘box-menu-item :text (string gray-name) 
:Stipple gray-array) 
‘value ,gray-array) es 
‘(,(or gray-name ‘“‘None’”’) 
‘value ,gray-name 
‘Style (nil ,(if gray-name :bold :italic) nil)))) 
“Choose a stipple pattern’’)) 


e @ Example—Present a menu of colors. 


This example displays a text string centered in a colored box. The function 
choose-primary-color presents a menu of primary colors on the mouse 
screen. 


(defflavor color-box-menu-item ((text “ *’) (width 0) (height 0) (alu tv:alu-setz)) ( ) 
-initable-instance-variables) 


(defmethod (:menu-bounding-box-size color-box-menu-item) (win &optional stop-x) 
stop-x ;; unused 
(multiple-value-bind (xs ys) 
(send win ’:compute-motion text 0 nil 0 0 ) 
(incf ys (Send win ’:line-height)) 
(values (+ xs (send win :compute-motion “ ” 0 nil O)) 
(+ ys (// ys 2))))) 


(defmethod (:menu-print color-box-menu-item) (window x y) 
(multiple-value-bind (xs ys) (send self ’: menu-bounding-box-size window) 
(send window :draw-rectangle xs ys x y alu) io 
(let ((space (send window :compute-motion “ ” 0 nil 0))) Bas 
(send window :draw-rectangle ; 
(— xS space space) (- ys (// ys 3)) 
(+ x space) (+ y (// ys 6) 1) 
(send window :erase-aluf)) Bl aes 
(send window :set-cursorpos (+ x space space) (+ y (// ys 4))) | oe 
(send window ':string-out text) 


))) 
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(defun choose-primary-color ( ) 
(let ((win (Send tv:mouse-sheet :screen))) 
(tv:menu-choose 
(loop for i in '(:red :green :blue) 
as alu = (or (send win :send-if-handles :compute-color-alu tv:alu-seta /) 
tv:alu-seta) 
collect ‘(,(make-instance ’color-box-menu-item :text 
(string i) :alu alu) 
:value (,i ,alu))) 
“Choose a color’’))) 
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Appendix E 
Bitmaps 


Four types of bitmaps are defined. These bitmaps are like windows and screens 
but are not as encumbered by the exposure and hierarchical requirements of 
real windows. Bitmaps are useful when you want to prepare an image for block 
transfer (bitblt) to a window but do not want it to be seen in the meantime. 
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The basic bitmap is tv:bitmap. Auxiliary types are tv:color-bitmap, 


Either type of bitmap can have multiple bits per pixel, but noncolor bitmaps 
reduce everything to the old-style fixnum ALUs. 


' 

tv:bitmap-screen, and tv:color-bitmap-screen. eee 
; eae 
The types with the suffix -screen are screens as far as the system is concerned. oe 
They appear on tv:all-the-screens and attract the mouse. You should not use ee 

the -screen flavors unless there is an outside mechanism that makes the bitmap esa 

IE visible. nos 
The types with the prefix color- understand the full semantics of extended ALU # fc 
objects and can look exactly like color screens. eee 

iz oo 


In summary you should normally use bitmap for 1-bit-per-pixel bitmaps and 
color-bitmap for multibit-per-pixel bitmaps. Normally you do not use the 
-screen types at all unless they are used as part of a more complex flavor 
mixture that makes them visible. See color-bitmap-on-real-screen for an 
example. 


f 


Creating Bitmaps 


Create a bitmap using make-instance, rather than tv:make-window. The 
most useful init options follow: 


:width (no default) 
sheight (no default) 
:bits-per-pixel (default to 1) fe 
:buffer-array The initial array from which to create the screen. If ee G 


:buffer-array is supplied, the number of bits per pixel, 
the width, and the height are deduced from it. 


if 
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Using Bitmaps 


Bitmaps accept the same messages as screens, streams, and all tv:graphics- 
mixin methods. This means you can treat bitmaps as windows. You can also 
create inferior windows on bitmaps by creating any kind of window and desig- 
nating the bitmap as the window's superior. 


color:color-bitmap-on-real-screen Flavor 
This flavor is a combination of tv:bitmap-screen, line-index-pan- 
zoom, and some additional methods. Because of hardware restrictions, the 
width must be a multiple of 32. The init options for color:color-bitmap- 
on-real-screen are the same as those for color:bitmap-screen and 
color:line-index-pan-zoom. 


al id Diced Te 


ee Example—Create and use a bitmap with a grid pattern. 


Hef 


(defvar *grid* nil) 


(defun grid-bitmap (&key (cell-x-size 10) (cell-y-size 10) (n-x-cells 10) (n-y-cells 10)) 
(let* ((bitmap-width (1+ (* cell-x-size n-x-cells))) 
(bitmap-height (1+ (* cell-y-size n-y-cells))) 
(bitmap (make-instance ‘tv:bitmap ‘note we use make-instance to 
‘create bitmaps, rather than 
‘tv:make-window 


~ 


-width bitmap-width 
‘height bitmap-height))) 


‘draw left and top lines 

. | (send bitmap :draw-lines tv:alu-seta 0 bitmap-height 0 0 bitmap-width 0) 
Hye | ‘draw vertical grid lines 
(loop for x from cell-x-size to bitmap-width by cell-x-size 

do (send bitmap :draw-line x 0 x bitmap-height)) 
‘draw horizontal grid lines 
(loop for y from cell-y-size to bitmap-height by cell-y-size 

do (send bitmap :draw-line 0 y bitmap-width y)) 
(setq *grid* bitmap))) 


re eI 


(defun show-grid (window x y) 
(let ((grid (or *grid* (grid-bitmap)))) 
(multiple-value-bind (gx gy) (send grid :size) 
(tv: prepare-sheet (grid) 
(send window :bitblt tv:alu-seta gx gy (tv:sheet-screen-array grid) 0 0 x y))))) 


bee - 
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Aliasing. Unpleasant jagged edges on an object. Sometimes called “jaggies” or 
“staircasing.’ See Antialiasing. 


Alpha key. A type of keying that specifies a key value per pixel. Sometimes 
called a soft key. Typically used to soft-matte two images. 


ALU. An old term meaning Arithmetic Logic Unit. An ALU, in a graphics con- 
text, describes how pixels are modified—in other words, what arithmetic or 
logical operation is performed on each pixel. A drawing operation, such as 
drawing a solid rectangle, can be thought of as specifying a set of pixels to 
be modified (the pixels within the rectangle). When working with one bit 
= per pixel, the inclusive-OR (IOR) ALU function sets each pixel to 1, the 
AND-with-complement (ANDCA) ALU sets each pixel to 0, and the le 
exclusive-OR (XOR) complements (flips) each pixel. All of the logical ALU | gees 
functions are readily described by a 4-bit number. In the case of more than | 
one bit per pixel, the specification is not always as simple, so an instance is 
acceptable in lieu of a number. This permits a greater range of expression. 
For example, “set each pixel to 7” is readily defined. An ALU such as IOR 
operates on every bit of the pixel, so IOR in an 8-bit system sets the pixel to 
255 (all bits set to 1s). 


Antialiasing. The name for a variety of techniques used to reduce jagged, ropy 
edges (known as aliasing, sometimes referred to as “jaggies”’ or “‘stair steps’) 
in computer graphics. Aliasing is a by-product of the analog-to-digital con- . 
version process, if the analog signals are digitized by periodic sampling. If | ae 


the sampling is not done often enough to capture all the information in the o 

analog signal, aliasing occurs. One antialiasing technique, sometimes called Ve 3 
supersampling, increases the sampling rate. This can reduce the aliasing, but ) Be: 
for typical graphic primitives like lines and polygons, which ideally have | | ee 
perfectly sharp edges, supersampling can never completely eliminate the |} 
aliasing. A better approach is to run the analog signal through a low-pass ay 
filter before sampling it. ae 


Array. Arrangement of values into rows and columns. In the context of a color 
display, these storage cells hold the values associated with pixels on the 
screen. Rows of cells form scanlines. 
re 
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Baby backplane. A small interconnection module that plugs into the existing 
backplane of any 3600-family machine. A baby backplane facilitates com- 
munication between the color controller, color paddle cards, and color 
memory boards. The color system uses two-, three- and five-slot baby back- 
planes. 


Backplane. An electromechanical packaging system on a PC board in the card 
cage. The backplane distributes address, control, and data signals between 
the CPU, memory, I/O, and any other board that plugs into the backplane 
connectors. 


Bandwidth. A measurement of information flow per unit time. Usually stated 
in terms of a range of frequencies that can be transmitted without signifi- 
cant losses. 


Bignum. An integer larger than can be held in one machine word. Common 
Lisp automatically uses bignums when the result of an integer calculation 
exceeds 32 bits. Unlike normal integers, bignums require allocating storage 
to contain them. 


Bit-mapped display. Essentially the same as a raster scan display with some 
number of memory bits assigned or mapped to each pixel. 


Blanking. The time during which the electron beam of a monitor is turned off 
and reset to its start position for either the next scanline or the next field. 


Coax. Short for coaxial cable. 


Coaxial cable. A type of “wire” used to connect the monitor to the system. 
RGB systems use one cable for each color and an optional fourth cable for 
sync. 


Color map. Also called lookup table (LUT). Pixel values stored at each location 
in color memory serve as address pointers to cells in the color map. The 
values stored at these addresses are sent to the DACs and then to the scan- 
ning guns. The color map in the high-resolution color system is composed 
of very high-speed static random-access memory. 


DACs. Digital-to-analog converters that reside on a paddle board and drive the 
color monitors. 


Dependent. A type of mapping technique where one copy of the pixel data is 
sent to all three (red, green, blue) channels, as is the case with pseudo-color 
systems. 


Direct color. Sometimes called full color. Uses a 24-bit frame buffer with three 
8-bit planes, one each for the red, green, and blue components of a pixel. 
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The number of distinct colors that can be displayed at one time is limited - 
only by the number of pixels in the frame. Sa 


False color. See Pseudo-color. 


Field. One of two interleaved portions of the screen in an interlaced scanning 
display system. 


Flavors. The implementation of object-oriented programming on a 3600-family na 
machine. A flavor is a description that defines local state variables (instance 
variables) and behaviors (methods), which operate on the local state. When : 
a flavor is instantiated, particular values are filled in for the local state in the fede 
new instance. When a message is sent to an instance, a behavior is selected toe 
at runtime and executed. General-purpose programs can be written to send 
messages to instances so that the details of what happens during execution | 
vary. A flavor can “inherit” from one or more other flavors. A flavor is simi- ie 

lar to a Smalltalk “class.” See Instance and Mixin. | 


Flicker. Sudden light fluctuation on a screen that occurs if the display is not 
refreshed at a sufficiently high rate. 


Flonum. A floating-point number. 


Frame grabber. A device that accepts video as an input, digitizes it, and stores 
the information in image memory. The digitizing frame grabber option digi- 7 
tizes one frame of RS-170(A) video in one frame time and stores it in an on- 
board frame buffer. Useful for machine vision, robotics, image 
understanding, and graphics applications. 
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Genlock. A circuit that synchronizes the frequency and phase of an internal 
sync generator to an external source. The genlock option synchronizes a 
3600-family color option to an external video signal or sync generator. 


High-order bit. The numerically most significant bit in a sequential grouping 
of bits. Complementing the high-order bit results in the largest change in 
magnitude of value, assuming the grouping represents an integer. 


Horizontal retrace. See Retrace. 


Huffman code. A scheme that compresses data by using fewer bits for com- 
monly occurring data. 


Icon. Pictorial representation of an object or concept. 


Independent. A type of mapping technique where three independent fields 
ig within the pixel drive the three (red, green, blue) channels, as is the case 
with 24-bit systems. 
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Instance. An object made from a particular flavor. It has specific values for the 
local state variables described by the flavor from which it is made. Its behav- 
ior comes from the methods described by the flavor. See Flavors. 


Interactive graphics. Dynamic interaction with a graphics system. The graph- 
ics system tracks a user’s gestures in real time and displays the results in real 
time. 


Interlaced scanning. Raster scanning method that divides the screen into two 
fields, alternately drawing odd- and even-numbered scanlines. Lines from 
each field are interwoven to create a single image. 


Jaggies. See Aliasing. 


Keying. Auxiliary video information produced on a fourth channel on some 
color controllers. Used to control video switches, to effect dissolves be- 
tween images, or to matte several images. 


Lbus. Main memory bus of the 3600-family processors. The processor commu- 
nicates with the color option over the Lbus. The Lbus transmits information 
at peak rates of 20 Mbytes per second. 


Line index table (LIT). A hardware pointer that points to the beginning and 
ending address locations of each scanline in color memory. 


Lookup table (LUT). See Color map. 
Low-order bit. The least significant bit. See High-order bit. 


Luminance. Amount of light emitted from a display. The gray level of a color 
image. 


Map mode. The type of color map processing that is done by the hardware. 


Map segment. A color map contains several segments, only one of which actu- 
ally drives the video at the moment. The map segment that is driving the 
video is called the primary color map segment. Each map segment contains 
specifications for the red, green, and blue intensity to be associated with 
each pixel value. The specifications vary with the hardware configuration. 


Matte. The map of where a composite image uses two images. In video, the 
matte (or key) signal switches between two images. 


Misconvergence. Improper alignment of the three electron beams of a color 
monitor, resulting in colored “fringes” and off-color images. 


Mixin. A kind of flavor that does not stand alone. For example, a window sys- 
tem can have a flavor called window, which is a complete window 
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without a label inside it or a border around it. The window flavor might 
also have a label-mixin and a borders-mixin. The window flavor is oe 
useful on its own, but label-mixin and borders- foe a are only useful pe 
when combined with window. See Flavors. | 


Noninterlaced scanning. A raster scanning method that draws all lines on a 
display from top to bottom in sequential order, usually at a rate of 60 times 
per second. 


Notch filter. A narrow-band stop filter. In NTSC video, notch filters are some- 
times used to filter the 3.58-MHz subcarrier signal out of the luminance 
signal. 


NTSC. National Television Standards Committee. A color encoding scheme 
used in the U.S., Japan, and South America. Also known as “Never Twice 
the Same Color.’ 


NTSC video. NTSC video uses a complex format to combine the red, green, 
and blue video signals into one signal. First, it transforms the RGB signals 
into three different signals: Y, I, and Q. The Y signal represents the gray, or 
luminance, value of the signal. The I and Q signals represent the color por- 
tion of the signal. The signals are separated for compatibility with black- 
and-white TV, which looks only at the Y signal and ignores the Iand Q 
signals. Next, the I and Q signals are combined onto the 3.58-MHz color 
subcarrier. Finally, the Y signal (luminance) and the color subcarrier are 
combined to produce the NTSC signal. NTSC video has a limited band- 
width, which yields color reproduction far inferior to RGB video. A high- 
quality NTSC sync generator is needed to generate good NTSC video. A 
sync generator with genlock capability allows the most flexibility because 
the sync generator can lock to some other source of video. NTSC video is 
converted to RGB video using an NTSC decoder. NTSC video requires one 
coaxial cable. 


Opaque overlay. An overlay plane that prevents any background information 
from being seen. See Transparent overlay. 


Paddle board. A small board that plugs in the rear of the card cage. Usually 
I/O connectors and a small amount of circuitry reside on this board. 


PAL. Phase Alternation (or Alternating) Line. A color encoding scheme used in 
Great Britain, Germany, and much of the world. Characterized by 625 lines 
per frame at 50 Hz. 


Persistence. The length of time it takes for a phosphor’s intensity to decay. 
Long-persistence phosphors emit light for a longer period of time after 
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electron beam stimulation ceases. This reduces flicker on static displays but ‘on 
causes “trails” on moving objects. a 


Phosphor. A substance which glows when hit with an energy source. The — 
coating on the inside surface of a CRT screen is made‘up of phosphor dots 
that emit light when hit by electrons from an electron gun. 


Pixel. Picture element. The smallest unit of the raster that can be stored, ad- = 
dressed, or displayed. 


Primaries. Set of three colors from which all other colors in the spectrum can —_ 
be produced. “4 
Primitive. Basic geometric element. a 
r= 
Pseudo-color. The pseudo-color system refers to the 8-bit mode of operation. 
Sy Raster. Pattern of horizontal lines scanned by the electron beams in the CRT as i 
a it draws the image on a display. ra 


a | Raster scan. System that scans or draws an image onto the screen in a succes- 
sion of scanlines. be 


Real time. Displaying an image or responding to a user’s request almost simul- 
ey | taneously with its occurrence. 


Recursion. Using something to define itself. See Recursion. “—_ 


Refresh. Rewriting of an image on the screen. The refresh rate refers to the — 
number of frames drawn on the screen per second. be 


Replacement overlay. An opaque overlay mode. 


Resolution. The number of pixels per line by the number of lines per frame, = 
or the number of pixels per inch. ) 


Retrace. Return of the electron beam to the left side or top of the screen after a = : 
horizontal or vertical scan. , 


RGB. Red, green, and blue. Often used to refer to a type of video color encod- - 
ing scheme and the type of color monitor that displays it. In RGB, a color is J : 
defined as percentages of red, green, and blue. 


RGB video. All Symbolics frame buffers generate three separate video signals, = 
one each for the red, green, and blue components of the picture. RGB | 
video has the following advantages over NTSC video: simplicity, a very high 
bandwidth, and color fidelity. RGB video is converted to NTSC video using 
an NTSC encoder. RGB video requires three coaxial cables. 
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Saturation. Degree to which a color is undiluted by white light. A color that is 
100 percent saturated contains no white light. 


Scanline. A line composed of individual pixels drawn on a:raster. 


Scanning. Process of writing or drawing a raster image on a monitor’s screen 
by successively addressing points on the display surface. 


SECAM. Systeme Electronique Couleur Avec Memoire (or Sequential Color with 
Memory). Color encoding scheme used in France, the USSR, and eastern 
European countries. Characterized by 625 lines at 50 Hz. Also known as 
“Supreme Effort to Counter American Methods.” 


Soft key. See Alpha key. 


Soft matte. A matte with intermediate values. Rather than a simple switch, the 
composite image becomes a blend of several images, where the matte values 
serve as the weight for the blend. 


Sync. Synchronous, synchronization, or synchronizing. The process of main- 
taining two or more scanning processes in phase. 


Sync generator. A device that generates the horizontal and vertical sync sig- 
nals. A programmable sync generator allows user selection of the signal 
format. 


Transparent overlay. An overlay plane through which some of the main 
frame buffer image can be seen. See Opaque overlay. 


Trimpot. Trim potentiometer. Analog adjustment in paddle boards. 


Vertical retrace. See Retrace. 
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:1-bit-parameters, message of color screens 50 i 
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a 
Access modes =113 ag 
Active screens, list of all (global variable tv:all-the-screens) 8 Re: 
Alpha channel 114 ie 
Alpha key mode 71 . 
ALU, see Color ALU ae 
:alu, init option of flavor general-sc-color-alu 50 es 
:alu, message of color screens 50 ao 
ALU operation code 46 os “ 
:array, init option of flavor general-sc-color-alu 47 © a 
:array, message of color screens 48 - s 
er 
B i 
ie 
:background-color, message to CAD buffer overlay screens 91 ie 
:binary-dump-forms, message of color screens (IMAN package) 153 
Bitmaps 203 % 
Bits per pixel 203 - 
Creating 203 ss 
Types 203 <d 
Using 204 a 
Black-level switch 115 | eae 
Block format, IMAN .dump file’s internal 158 | ie Ee 
Broadcast-resolution color system 122 Wee 
I 
C lea 
IF 
CAD buffer color system f 
Color map modes 87, 89 > 
External overlay array 88 - : 
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CAD buffer II color system 124 oe 
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char-aluf, window instance variable 44 
choose-framegrab-parameters, function 86 
Chroma color system 121 — 
Chroma key color selection 71 —— 
Chroma key mode _ 71 
Chroma key output 114 
:chroma-key-blanking-select, message of color screens 74 = 
:chroma-key-mode, message of color screens 72 
:chroma-key-modes, message of color screens 72 
:chroma-key-select, message of color screens 73 , f 
Color ALU 1, 39, 40 ~ 
As a drawing argument 97 
Color ALUs of several different types, how to create 95 
Default flavor 42 
Default type 40 
:fill-data instance variable for an ALU object 40 
Font handling capabilities 41 = 
How to use for drawing operations 40 
Instance, producing 97 
Operation code 46 a 
Making instances of 42 
Reusing 106 
Specifying colors with 97 —_ 
Types of operations that use 39 a 
Using the plane-mask field of 104 
Color controller 112 
Color demonstration system be 
Demonstration programs 187 
Diagnosing problems 185 
Ending 184 b 
Loading 184 
Test programs 184 
Color editor 125 = 
Changing the configuration 131 
Creating a color editor window froma program 126 
Functions called to invoke 126 b. 
Loading 125 ec. 
Result of invoking 126 
Color hardware, how the color system software configures automatically 163 
Color map, or color lookup table 1, 21 
8-bit versus 24-bit 24 
Changing the colormap 98 
Example of changing the color map 99 
Map management strategy 24 
Messages regarding 27 
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Modifying 95 ‘9 
Resetting from the color demonstration system 184 | 
Sizes foreach system 115 a 
Color map segments 21 be i 
Manipulating 99 i ; 
Color mixing 186 ee 
Color models 53 Ee 
Changing the selection 132 “a 
Transformations 55 ‘oes 
Color monitor 1 2 
Color object 1,53 te 
Creating 53 = 
Property lists 56 Bee 
Color palette display 127 A 
Color screen 1 pe 
Bit-save arrayson 5 eo ; 
Color screens and windows, creating and manipulating 3,5 aa 2 
Correcting common problems with 18, 163 +H 
Creating 5 — 
Creating windows on 5 ee ‘ ‘ 
Overlapping windows on 5 naa 
Color system ae 
Getting information about 17 ee 
Hardware terms 111 7) 
Software, loading 5 i ‘* y 
Color window 1 ae 
Simplest way to create 96 ee: 
color-bitmap-on-real-screen, flavor 204 2 
color-boards-present, function 164 oe 
:color-component, message of color objects 58 eu 
color-controllers, function 17 aie 
:color-map, message of color screens 28 ' i . 
:color-map-description, message of color screens 28 ae 
:cOlor-map-image, message of color screens 33 e ie 
:color-model, message of color objects 57 ca fF 
color-resources-string, function 18 oar 
color-system-description, function 18 : 
Colors on monitor ‘on 
Changing 98 Fe ,/ 
Not clear 166 ee 
Composite sync 87 at 
:compute-color-alu, message of colorscreens 45 fi 
:Ccompute-rgb-data, message of color screens 37 ates 
:compute-rgb-slots, message of color screens 37 7 te x 
Continuous update of color editor display 130 : ae 
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:control, message of color screens 69 

:control-image, message of color screens 69 

Create an image from scratch 141 

:create-1b-image, message of color screens (IMAN package) 146 
:create-3 2b-image, message of color screens (IMAN package) 148 
:create-8b-image, message of color screens (IMAN package) 146 
:create-bit-arrays, message of color screens (IMAN package) 141 
create-color-screen, function 7 

:create-init-plist, message of color screens (IMAN package) 153 
:create-rgb-image, message of color screens (IMAN package) 148 
:create-scaled-image, message of color screens (IMAN package) 154 
Creating screens, dangers of 6 

:cursor-image, message of color screens 69 

:cursor-visible?, message of color screens 69 


:data-array, message of color screens (IMAN package) 142 
default-grab-parameters, function 84 

:default-map-mode, message of color screens 30 
:default-map-segment-number, message of color screens 34 
demo-window, function 17 

Determining which boards are plugged in and working 164 
:discard-bit-arrays, message of color screens (IMAN package) 142 
Dithering 148 

:draw-convex-polygon, message to window using tv:graphics-mixin 173 
:draw-filled-in-simple-ellipse, message to window using tv:graphics-mixin 173 
:draw-polygon, message to window using tv:graphics-mixin 173 
:draw-simple-ellipse, message to window using tv:graphics-mixin 173 


edit-color, function 126 

Editingacolor 130 

Embedded overlay 91, 117 

erase-aluf, window instance variable 44 

External power connector on paddle boards 164 

External trigger 81, 86 

:external-trigger-enable, message of frame grabber screens 86 
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Fill mode 114 
:fill-area, message to window using tv:graphics-mixin 176 
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:fill-data, init option of flavor general-sc-color-alu 48 . 
:fill-data, message of color screens 49 | 
find-color-screen, function 5,8 ‘ : 
on find-image, function (IMAN package) 136 Pag 
'f find-images, function (IMAN package) 136 rip *, 
:find-scaled-image, message of color screens (IMAN package) 157 gt 
pit :flonum-rgb-for-color, message of color screens 51 3 = 
a Foreground overlay 117 a 
<i :foreground-color, message to CAD buffer overlay screens 90 cam 
Frame buffer 111 | : 
) if Frame grabber 125 ie 
- Making a PAL-format screen for use with 75 a 
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Making an NTSC-format screen for use with 75 

Messages 74 

Screens 85 

Selection, arguments to function create-color-screen 8 
:full-color-p, message of color screens (IMAN package) 142 
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Gamma correction 27 a : 
general-sc-color-alu, flavor 39, 47 Ree 
a Genlock 114 . 
Making sure the screen uses 171 
:get, message of color screens (IMAN package) 142 = 
:get-color-named, message of color screens 37 ae 
Global pan registers 113 Dy 
Global zoom registers 113 . 
grab-frame, function 75, 76 . 
:grab-frame, message of frame grabber screens 75, 76 4 
Hardware configurations 119 ates 
Hardware cursor 114 ss f 
hardware-rgb, function 57 ae 
hardware-rgb->rgb, macro 56 “Sige 
sheight, init option 142 oad 
sheight, message of color screens (IMAN package) 142 i 
Hexcone-IHS color model 53, 54 cg 
hexcone-ihs->rgb, macro 56 eee 
High-resolution color system 119 ; 
Hue 54 : 
| ‘ : ra 
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Icons, usingin menus 199 
IHS color model 53, 54 
Image compression techniques 148 
Image Management System, See IMAN 
Image manipulation using IMAN_ 136 
Image scaling 154 
Image types, transforming to other types 145 
:image-dump-form, message of color screens (IMAN package) 153 
Image-viewing functions 156 
Images 

Manipulating 136 

Storing slo, 

Used in IMAN 136 
IMAN_ 135 

Image manipulation 136 

Images used 135 
Incremental update of color editor display 130 
:init-color-map, message of color screens 33 
:init-managed-color-map, message of color screens 34 
:initialize-color-map, message of color screens 33 
:initialize-line-index-table, message of color screens 66 
:inside-size, message of color screens (IMAN package) 142 
Intensity 54 
RESUS 7/0 


J 


Jittering 149 
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:keep-mouse-visible-p, message of color screens 63 
Key capability 70 

:key-set-pan-zoom, message of color screens 65 
kill-image, function (IMAN package) 137 
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line indexitable(iii).-O5, 415 

line-index-pan-zoom capability 61 
line-index-pan-zoom, flavor 67 
:line-index-pan-zoom, message of color screens 66, 68 
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:line-index-table, message of color screens 66 a. 
:line-index-table-image, message of color screens 66 | i 
:line-pan-zoom-for-line, message of color screens 68 | Pe 
:line-pan-zoom-image-from-line, message of color screens 68 _ s 
load-image-file, function (IMAN package) 137 ee - 
:load-image-file, message of color screens (IMAN package) 142 ah 
load-image-file-into-window, function (IMAN package) 137 ee: 
load-images, function (IMAN package) 137 Fae 
‘oy 
M {eee 
ae 
:make-color-map-image, message of color screens 33 ie 
make-color-screen, function 11 | base’ 
:make-control-image, message of color screens 70 Ks ey 
make-framegrab-screen, function 75 BR 
make-image, function (IMAN package) 142 ca 
:make-line-index-table-image, message of color screens 66 eee 
make-wide-font, function 42 = oz: 
Map modes 1, 116 tg Ge 
Unique to CAD buffer 87, 89 ae 
:map-manager, message of color screens 36 2 ws 
:map-mode, message of color screens 31 he 
:map-modes, message of color screens 30 | 34 g 
:map-segment-number, message of color screens 34 | be ‘ 
:menu-blinker-edges, message of color screens 199 [Ss Z | 
:menu-bounding-box-size, message of color screens 199 ee : oF 
:menu-bounding-box-size, message of color screens (IMAN package) 157 | ai ; 
:menu-icons, keyword argument to all image-viewing functions 156 |e “ae 
:menu-print, message of color screens (IMAN package) 157 : 
:menu-print, message of color screens 199 | th 
Monitor not syncing to video 167 ong ; : 
:mouse-pan-zoom, message of color screens 64 * ie 
:multiple-set-chroma-key-blanking-select, message of color screens iS | 1G 
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:multiple-set-chroma-key-select, message of color screens 73 


mame, initoption 143 

:mame, message of color screens (IMAN package) 143 
:name-color, message of color screens 36 
:name-colors, message of color screens 36 
:new-color-map, message of color screens 34 
:new-control, message of color screens 70 
:new-cursor, message of color screens 69 


Index 


-_ J 
monensin 
sen ei 


4 = é = as 
EE ee ee ii le eS 


:new-line-index-table, message of color screens 66 
:new-line-index-table-array, message of color screens 66 
Nondefault image types, storing additional information with animage 152 


Opaque overlay 117 
Overlay 
Capabilities 115 
Effects 26, 30 
Replacement overlay 26, 30 
Simulating without special hardware support 26 
Transparent overlay 26, 30 
:Overlay-color, message to CAD buffer screens 91 
:overlay-description, message of color screens 29 
:Ooverlay-screen, message to CAD buffer screens 88 
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Packed mode 114 

:pan, message of color screens 62 

Pan and zoom, interactive methods for setting 64 
:pan-and-zoom, message of color screens 63 
:pan-and-zoom-from-rectangle, message of color screens 64 
:pan-and-zoom-from-rectangle-maybe, message of color screens 64 
:pan-and-zoom-p, message of color screens 63 
:pan-from-rectangle, message of color screens 64 
:pan-zoom-from-mouse-rectangle, message of color screens 65 
:pan-zoom-visible-edges, message of color screens 64 
Peano-mapping 149 

Pixel mode 113 

:pixel-mask, init option of flavor general-sc-color-alu 49 
:pixel-mask, message of color screens 49 

:pixel-positions, message of color screens 32 

:plane-mask, init option of flavor general-sc-color-alu 49 
:plane-mask, message of color screens 49 

Predefined image types 140 

:property-list, message of color screens (IMAN package) 143 
:putprop, message of color screens (IMAN package) 143 


:read-color-map, message of color screens 35 
:read-color-map-image, message of color screens 35 
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:read-managed-map, message of color screens 36 
:remprop, message of color screens (IMAN package) 143 
Replacement overlays, simulating 101 

Resolution 111 

:reverse-video-p, message of color screens 37 
:rgb, message of color screens (IMAN package) 143 
RGB color model 53,55 

rgb->hardware-rgb, macro 56 
rgb->hexcone-ihs, macro 55 

rgb->ihs, macro 55 

rgb->yigq, macro 55 

:rgb-for-color, message of color screens 51 
Run-length/delta-encoded data 159 
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Saturation 55 
save-window, function (IMAN package) 137 
sc-fill-alu, function 45 
:SC-parameters, message of color screens 50 
Scaled images, underlying functions used to create 155 
Screen array 1 

1-bit accessed in CAD buffer -with- modes 88 

Manipulating 2 
Screen type and video source combinations 78 
Screen visibility (CAD buffer screens), determining current 87 
Screens, three most common combinations of frame grabber with 85 
:send-image-to-window, message of color screens (IMAN package) 143 
:set-alu, message of color screens 50 
:set-array, message of color screens 48 
:set-background-color, message to CAD buffer overlay screens 91 
:set-blue, message of color screens (IMAN package) 143 
:set-bow-mode, message of color screens 37 
:set-bow-mode, message of screens 19 
:set-chroma-key-blanking-select, message of color screens 74 
:set-chroma-key-mode, message of color screens 73 
:set-chroma-key-select, message of color screens 73 
:set-color-map-image, message of color screens 32 
:set-color-model, message of color objects 57 
:set-component, message of color objects 58 
:set-cursor-position, message of color screens 69 
:set-cursor-visible?, message of color screens 69 
:set-data-array, message of color screens (IMAN package) 142 
:set-default-map-segment-number, message of color screens 35 
:set-external-trigger-enable, message of frame grabber screens 86 
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:Set-fill-data, message of color screens 49 
:set-foreground-color, message to CAD buffer overlay screens 90 
:set-green, message of color screens (IMAN package) 143 
:set-height, message of color screens (IMAN package) 142 
:Set-init-color-map, message of color screens 33 vex 
:set-keep-mouse-visible-p, message of color screens 63 
:Set-line-index-pan-zoom, message of color screens 67 
:set-line-index-table-image, message of color screens 66 
:set-line-pan-zoom-for-line, message of color screens 68 
:Set-line-pan-zoom-image-from-line, message of color screens 68 
i :set-map-mode, message of color screens 32 
:set-map-segment-number, message of color screens 34 
:set-name, message of color screens (IMAN package) 143 
:set-overlay-color, message to CAD buffer screens 91 
} :set-pan, message of color screens 62 
: :Set-pan-and-zoom, message of color screens 63 
:Sset-pixel-mask, message of color screens 49 
:Sset-plane-mask, message of color screens 49 
:set-red, message of color screens (IMAN package) 143 
:Sset-reverse-video-p, message of color screens 37 
:set-setup-color-map, message of color screens (IMAN package) 144 
:Sset-soft-key-value, message of color screens 73 
:set-width, message of color screens (IMAN package) 144 
q :set-wrap, message of color screens 62 
| :set-x-pan-from-lit, message of color screens 68 
:set-x-zoom-from-lit, message of color screens 68 
:Set-zoom, message of color screens 63 
:setup-color-map, init option 144 
:setup-color-map, message of color screens (IMAN package) 144 
:Size, message of color screens (IMAN package) 143 
:SOft-key-value, message of color screens 73 
Software overlay effects 100 
Standard sync programs 168 
standard-color, color object flavor 58 
:Standardize-color-map, message of color screens 33 
Stored images, file format used for 157 
Sync generator 114 - 
Sync programs 167 
Creating 170 | 
Directory in which they are stored 167 a 
Nondefault 167 ; a 
Standard 168 
Sync select jumper 87 
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:Sync-source, message of frame grabber screens 87 - 
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:take-image-from-window, message of color screens (IMAN package) 
:transfer-frame, message of frame grabber screens 77, 78, 83 

Defaults 80, 84 
:transfer-scaled-image, message of color screens (IMAN package) 155 
Transparent overlays, simulating 104 
tv:all-the-screens, global variable 8 


:update-color-map-from-image, message of color screens 36 
Using hardware overlay effects 107 
Using the mouse to select boundaries for screens 96 
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Video source and screen type, four common combinations 78 
view-image, function (IMAN package) 139 
:visible-size, message of color screens 64 
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:wait-for-external-trigger, message of frame grabber screens 81, 86 
:wait-for-grab-done, message of frame grabber screens 77 
:warp-mouse-to-be-visible, message of color screens 63 
:width, init option 144 

:width, message of color screens (IMAN package) 144 
:wrap, message of color screens 62 

:write-color-map, message of color screens 36 
:write-color-map-image, message of color screens 36 
:write-files, message of color screens (IMAN package) 145 
write-image, function (IMAN package) 140 
:write-managed-map, message of color screens 36 
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:x-pan-from-lit, message of color screens 68 
:x-zoom-from-lit, message of color screens 68 
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YIQ color model 53, 54 
yiq->rgb, macro 55 
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:zoom, message Of color screens 63 
zoom-rectangle, function 155 
zoom-window-mixin, flavor 65 
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